diff --git a/www/docs/agents/agent-platform-overview.md b/www/docs/agents/agent-platform-overview.md index f678a3023..14d471841 100644 --- a/www/docs/agents/agent-platform-overview.md +++ b/www/docs/agents/agent-platform-overview.md @@ -1,171 +1,93 @@ --- 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. - -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** |
  1. Agent handles L1 support
  2. Searches knowledge bases
  3. Escalates complex issues
  4. Creates tickets
| -| **Build intelligent research assistants** |
  1. Agent searches multiple data sources
  2. Synthesizes findings
  3. Maintains research context across sessions
| -| **Create workflow automation systems** |
  1. Agent triggers business processes
  2. Sends notifications
  3. Updates CRM systems based on natural language requests
| -| **Develop conversational enterprise tools** |
  1. Agent maintains context
  2. Handles multi-step processes
  3. Integrates with existing business systems
| -| **Deploy autonomous business processes** |
  1. Agent monitors conditions
  2. Makes decisions
  3. Executes actions without human intervention
| - -:::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: +Agents are autonomous systems that understand natural language and use tools +and reasoning to accomplish tasks. -* 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. +## Getting Started -## Agents +To build your first agent: -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. +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. -## Tools -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). +:::tip Quick Start +For a complete step-by-step guide with code examples, see +[**Agent Quick Start**](/docs/agents/agents-quickstart). +::: -## 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.
```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 + + %% 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:#fff,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:#fff,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 } ```
-## 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. - diff --git a/www/docs/agents/agents-quickstart.md b/www/docs/agents/agents-quickstart.md index c8e1724e5..70af14c7c 100644 --- a/www/docs/agents/agents-quickstart.md +++ b/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 diff --git a/www/docs/agents/agents.md b/www/docs/agents/agents.md index 8be70bd96..f52aced29 100644 --- a/www/docs/agents/agents.md +++ b/www/docs/agents/agents.md @@ -6,20 +6,26 @@ sidebar_label: Agent import CodePanel from '@site/src/theme/CodePanel'; -Agents are the core orchestration unit in the Vectara platform. The -agent decides how to respond to user input, when to invoke tools, and how to -manage conversation state. +Agents are autonomous systems that understand natural language and use tools +and reasoning to accomplish tasks. To do this, they must make decisions: + +* Interpreting user input +* Calling tools, and with what arguments +* Managing conversation state + +Internally, they use an LLM-driven orchestration pipeline to make these +decisions. ```mermaid flowchart TD %% User Input and Response Flow - User[User Query] --> Reasoning[Reasoning LLM Brain Understand user query and intent] - Reasoning --> Planning[Planning Build execution plan using available tools] - Planning --> Response[Response Collect information and respond] + User[User Query] --> LLM[LLM Reasoning and planning] + + LLM --> Response[Collect information] Response --> Output[Response] %% Orchestration Flow - Planning --> OP + LLM --> OP %% Tools and Agents in Orchestration Pipeline subgraph OP[πŸ”§ **Orchestration Pipeline** πŸ”§] @@ -31,7 +37,7 @@ flowchart TD end %% Orchestration pipeline links outside agent - + Tool1 <--> RAG1[Vectara RAG 1] Tool2 <--> RAG2[Vectara RAG 2] Tool3 <--> API[API] @@ -40,8 +46,7 @@ flowchart TD %% Grouping subgraph Agent [πŸ’­ **Agent** πŸ’­] - Reasoning - Planning + LLM Response OP end @@ -51,147 +56,40 @@ flowchart TD classDef tools fill:#E6FFFA,stroke:#319795,color:#000; classDef sources fill:#FFF5F5,stroke:#E53E3E,color:#000; - class Reasoning,Planning,Response llm; + class LLM,Response llm; class OP pipeline; class Tool1,Tool2,Tool3,Agent1,Agent2 tools; class RAG1,RAG2,API,DB,Custom sources; ``` +## LLM configuration -Each agent is configured with: - -* A unique key and name following the pattern agt_[identifier]. If you do not - provide a key, Vectara generates one automatically based on the name. -* A human-readable description -* Optional instructions -* A list of available tools (referenced by name or ID) -* Optional tool configurations, for example Corpora Search tools configured - to grant access to various corpora -* Metadata and versioning controls -* A _first_step_ definition that encompasses optional instructions for the - agent's behavior. - -Agents operate through a conversational step architecture, processing user -input through reasoning, tool execution, and response generation phases. -The step-based design enables complex multi-turn workflows and intelligent -tool orchestration. - -:::tip Create an agent -You can create an agent in the [**Vectara Console**](/docs/console-ui/agents/create-an-agent), or you can use the -API. For more information, check out our [**Agents Quick Start**](/docs/agents/agents-quickstart). -::: - -## Example agent definition - -This example shows a basic customer support agent configured with corpus search capabilities and inline instructions. The agent demonstrates the core components: tool configurations for searching support tickets, and a conversational first step with behavior guidelines. - - - -## Model configuration - -Agents use large language models for reasoning and response generation. You -can configure: - +Agents use LLMs for reasoning and response generation. You can configure the +following: - **Model**: Choose from available models like GPT-4o. -- **Parameters**: Adjust temperature, max tokens, and other model-specific settings -- **Cost optimization**: Balance performance with token usage -- **Retry configuration**: Configure automatic retry behavior for transient failures +- **Parameters**: Adjust temperature, max tokens, and other model-specific settings. +- **Cost optimization**: Balance performance with token usage. +- **Retry configuration**: Configure automatic retry behavior for transient failures. -### Retry configuration +## Using retries to improve user experience -When agents interact with LLMs, transient failures may occur that interrupt -the conversation flow, including network timeouts, temporary server issues, -or reaching API rate limits. Without a retry mechanism, these temporary -issues cause your agent to fail immediately, resulting in a poor user +When agents interact with LLMs, transient failures like network interruptions +can disrupt communication between the agent and the LLM. You can configure +your agent to resume disrupted communication to ensure a smooth user experience. -Vectara provides a retry configuration option for agents which detects these -recoverable failures and retries the request with exponential backoff -automatically. - -The `RetryConfiguration` object controls the retry behavior for your agent's -interactions with the LLM. You define these settings when creating or -updating your agent model, and they apply to all LLM requests made by that -agent. - -### Retry configuration parameters +Here's a brief explanation of how retries work: -- **enabled**: The boolean flag to enable or disable retry logic - - Default: `true` -- **max_retries**: The maximum number of retry attempts after the initial failure - - Range: 0-10 - - Default: `3` -- **initial_backoff_ms**: The initial delay in milliseconds before the first retry - - Range: 100-60000ms - - Default: `1000ms` -- **max_backoff_ms**: The maximum delay in milliseconds between retries - - Range: 1000-300000ms - - Default: `30000ms` -- **backoff_factor**: The exponential multiplier for calculating backoff delays - - Range: 1.0-10.0 - - Default: `2.0` +- **max_retries:** After an error, the agent will retry its request to the LLM this many + times. +- **initial_backoff_ms:** This is how many milliseconds the agent will wait before + retrying, to give the cause of the error time to resolve. +- **backoff_factor:** Every time the agent retries, it can multiply the last retry + delay by this number, increasing the wait between retries. This is like giving a + toddler a longer and longer timeout if it continues to misbehave. +- **max_backoff_ms:** The maximum time you want the agent to wait between retries, + so the backoff_factor doesn't create an unreasonably long delay for your users. -### Exponential backoff - -Exponential backoff progressively increases the delay between retry attempts -to avoid overwhelming a recovering service. For example, with default -settings (initial: 1000ms, factor: 2.0, max: 30000ms): - -- Attempt 1: 1000ms delay -- Attempt 2: 2000ms delay -- Attempt 3: 4000ms delay -- Attempt 4: 8000ms delay - -The delay continues to grow exponentially until it reaches the -`max_backoff_ms` value, at which point it remains constant for any remaining -retry attempts. - ### Example: Research assistant with web search Here's how to create a research assistant agent that can search the web for @@ -250,97 +148,36 @@ This example requires no corpus setup, making it perfect for immediate testing. ]} annotations={{ bash: [ - { line: 1, text: 'Use backslashes for line continuation in bash' }, - { line: 2, text: 'Replace YOUR_API_KEY with your actual API key' }, - { line: 5, text: 'Unique name for your agent' }, - { line: 6, text: 'Human-readable description' }, - { line: 8, text: 'Configure available tools' }, - { line: 9, text: 'Enable web search tool' }, - { line: 14, text: 'Define conversational behavior' }, - { line: 16, text: 'Instruction type must be "inline"' }, - { line: 17, text: 'Name is required for inline instructions' }, - { line: 18, text: 'Agent personality and guidelines' }, - { line: 24, text: 'Model configuration' }, - { line: 25, text: 'Using gpt-5 model' }, - { line: 27, text: 'Lower temperature for factual responses' }, - { line: 28, text: 'Maximum response length' }, - { line: 30, text: 'Retry configuration for handling transient failures' }, - { line: 31, text: 'Enable automatic retry logic' }, - { line: 32, text: 'Retry up to 3 times on failure' }, - { line: 33, text: 'Start with 1 second delay before first retry' }, - { line: 34, text: 'Cap maximum delay at 30 seconds' }, - { line: 35, text: 'Double the delay between each retry attempt' } + { line: 1, text: 'POST request to create a new agent' }, + { line: 2, text: 'Authorization header with your API key' }, + { line: 3, text: 'Content type for JSON payload' }, + { line: 5, text: 'Unique identifier name for the agent' }, + { line: 6, text: 'Human-readable description of agent purpose' }, + { line: 7, text: 'Tool configurations defining available capabilities' }, + { line: 8, text: 'Web search tool for real-time information' }, + { line: 9, text: 'Tool type identifier for web search' }, + { line: 12, text: 'First step configuration for agent entry point' }, + { line: 13, text: 'Conversational type for interactive chat behavior' }, + { line: 14, text: 'Instructions array defining agent behavior' }, + { line: 15, text: 'Inline instruction type for embedded prompts' }, + { line: 16, text: 'Name identifier for this instruction set' }, + { line: 17, text: 'Template defining agent personality and guidelines' }, + { line: 23, text: 'Model configuration for LLM settings' }, + { line: 24, text: 'Specify gpt-5 as the reasoning model' }, + { line: 26, text: 'Temperature 0.3 for consistent, factual responses' }, + { line: 27, text: 'Maximum token limit for responses' }, + { line: 29, text: 'Retry configuration for handling transient failures' }, + { line: 30, text: 'Enable automatic retry logic' }, + { line: 31, text: 'Maximum of 3 retry attempts on failure' }, + { line: 32, text: 'Initial 1 second delay before first retry' }, + { line: 33, text: 'Maximum 30 second delay between retries' }, + { line: 34, text: 'Exponential backoff factor of 2.0 between retries' } ] }} layout="stacked" /> -## Chat with your agent - -After creating an agent, you can interact with it by creating a session and sending messages: - -### 1. Create a session - -Sessions provide conversation context and are required for all agent interactions: +To chat with your agent, read on about [Sessions](/docs/agents/sessions). - - -### 2. Send messages to the agent - -Once you have a session, send messages using the events endpoint: - - -The agent will respond with events including its reasoning, tool usage, and final response. -:::tip Quick Start -For a complete step-by-step guide with code examples, see [Agent Quick Start](/docs/agents/agents-quickstart). -::: \ No newline at end of file diff --git a/www/docs/agents/instructions.md b/www/docs/agents/instructions.md index cc031706e..7dc286556 100644 --- a/www/docs/agents/instructions.md +++ b/www/docs/agents/instructions.md @@ -6,113 +6,98 @@ sidebar_label: Instructions import CodePanel from '@site/src/theme/CodePanel'; -Instructions serve as reusable blocks of system prompt logic. They guide the -reasoning and behavior of an agent by setting expectations, prompts, -and providing the rules for the underlying Large Language Model (LLM). - -Instructions use the [Apache Velocity](https://velocity.apache.org/) templating -engine, which enables you to dynamically insert variables into your prompts. -You can configure instructions for an agent in two ways: **inline** or -**shared**. - -## Inline Instructions - -You define inline instructions when you configure an agent. These instructions -are specific to that agent and best for situations that do not require reuse. - -- **Type**: To specify an inline instruction, set the `type` field to `"inline"`. -- **Lifecycle**: An inline instruction is automatically deleted if the agent it - belongs to is deleted. - - - -## Shared (Reference) Instructions - -You can create shared instructions as independent, versioned entities for reuse -across multiple agents. This is ideal for standardizing behavior, such as -enforcing brand voice or defining common workflows. - -A shared instruction consists of the following: -* A unique ID (`ins_12345`). -* A `name` and `description`. -* A `prompt` template. -* Optional `metadata` for organization. -* A `version` for tracking updates. - -To use a shared instruction, set the `type` field to `"reference"` -and provide the instruction's unique `id`. - -:::note -When you update a shared instruction, this creates a new version of that -instruction. To use the new version, you must update any agents that -reference the instruction. If you do not specify a version, the agent uses -the latest one. +An agent's behavior is defined by the instructions you give it. The agent uses +these instructions alongside information from a conversation session to +determine how to respond to user input, including which tools to use. + +:::tip Note +Instructions in Vectara are referred to **system prompts** in other LLM APIs +(such as Gemini, Mistral, and OpenAI). If you are familiar with _system prompts_ +terminology, instructions serve a similar purpose. Instructions define the +role, behavior, and guidelines of an agent before any user interaction begins. ::: - - -## Template Context - -The Velocity templating engine has access to contextual information during -execution, such as the results from tool calls. This allows you to create -dynamic and responsive instructions. For this version, agent and session -context are not included in the template scope. +} +``` + +The instruction renders as: +> "Hello! I see you're John Doe from North America. I'm here to help you with billing inquiries." \ No newline at end of file diff --git a/www/docs/agents/sessions.md b/www/docs/agents/sessions.md index f93594b44..3109d3463 100644 --- a/www/docs/agents/sessions.md +++ b/www/docs/agents/sessions.md @@ -6,116 +6,313 @@ sidebar_label: Sessions import CodePanel from '@site/src/theme/CodePanel'; -A session is a contextual container for a conversation between a user (or -application) and an agent. It provides continuity across multiple -interactions. Key properties include: +Agents keep track of their conversations with sessions. One conversation is +one session. To begin chatting with an agent, you need to create a session +first. Each message sent by the user and each response from the agent is +appended to the session. * A session key and human-readable name (`ase_12345`). If not provided, Vectara generates one automatically based on the name. -* Associated `agent_key` (`agt_abcd`) -* Metadata such as end_user_id, application_id, priority, or channel -* Timestamps for creation and last update +* Associated `agent_key` (`agt_abcd`). +* Metadata such as end_user_id, application_id, priority, or channel. +* Timestamps for creation and last update. Sessions support lifecycle operations such as creation, update, retrieval, listing, and deletion. -## Agent events +## Chat with your agent -Each session contains one or more events, representing individual interactions -and system activities within the conversation: +After creating an agent, you can interact with it by creating a session and sending messages: -- **Input message events**: User input with text content -- **Thinking events**: Agent reasoning and chain-of-thought processes -- **Tool input/output events**: Tool execution with parameters and results -- **Agent output events**: Final agent responses to user input +### 1. Create a session -Events support both synchronous and streaming delivery, enabling real-time -conversation experiences with progressive response building. +Sessions provide conversation context and are required for all agent interactions: -### Example session and event + + +### 2. Send messages to the agent + +Once you have a session, send messages using the events endpoint: -### Session workflow example +The agent will respond with events including its reasoning, tool usage, and +final response. + +## Define session context with session metadata + +Let's say you want to make the agent aware of the user's preferred language, +so that it can respond in that language. Or imagine you want to tell the agent +that the user is only permitted access to a specific type of data. You can do +all this with session metadata. Session metadata enables you to inject +arbitrary information into the session context, which your instructions and +tools can refer to. + +Session metadata provides context-specific data to agents, enabling +personalization, security controls, and dynamic behavior. This key-value +data attaches to a session and becomes accessible as follows: + +- **Agent instructions** (Velocity templates) using `${session.metadata.field}` syntax +- **Tool configurations** (argument overrides) using `{"$ref": "session.metadata.field"}` syntax + -Here's how to create a session and start chatting with an agent: +Here's how you might implement the language preference and access control examples. + +### Example session with metadata -# Response includes session key: ase_abc123 +Then you'd write an instruction like this, to respond in the preferred +language. -# Step 2: Send a message in the session -curl -X POST https://api.vectara.io/v2/agents/agt_customer_support/sessions/ase_abc123/events \ - -H "Authorization: Bearer YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "type": "input_message", - "messages": [{ - "type": "text", - "content": "My order #12345 hasn\'t arrived yet" - }] - }'` + + +And you'd configure a corpora search tool like this, to limit the user's +access to certain corpora. + + + +## Artifacts + +Artifacts are files stored in an agent session's workspace that provide a +persistent, session-scoped storage mechanism. They enable agents and users to +share files throughout a conversation without bloating the agent’s context +with content from large files. + +Before artifacts, file uploads were handled inline within session events. +Artifacts solve these problems by separating file storage from file +references. When you upload a file, Vectara stores it in the session workspace +and returns a lightweight `ArtifactReference` containing only metadata. Agents +use these references to access files without including the full content in +every request. + +### How artifacts work + +Artifacts are created either in user uploads or tool generation, where agent +tools can create new artifacts as outputs. For example, converting a document +to markdown. + +Each artifact receives a unique identifier following the pattern art_[a-z0-9_-]+. + +### How agents use artifacts + +After files are uploaded as artifacts, the agent can: +- Use document conversion tools to extract content from PDFs, Word documents, + or PowerPoint files. +- Reference artifacts in analysis or question-answering workflows. +- Pass artifacts to indexing tools to add content to corpora. +- Create new artifacts as outputs of tool operations. + +Artifacts remain available throughout the session lifecycle, enabling multi-step +workflows without re-uploading files. + +## Working with artifacts in sessions + +Sessions provide a workspace where agents can access and process files +uploaded by users or generated by tools. These files are stored as artifacts +that enable efficient file handling without bloating the agent's context. + +To make files available to an agent, upload them to the session workspace +using a multipart request. Files are stored as artifacts and can be referenced +throughout the conversation. + +After files are uploaded as artifacts, the agent can extract content from +PDFs, Word documents, or PowerPoint files and reference artifacts during +conversations. Artifacts remain available throughout the session lifecycle, +enabling multi-step workflows without re-uploading files. + +### Example: Upload files to session + + + -:::tip -Sessions persist conversation history, so subsequent messages in the same session will have context of previous interactions. This enables natural, multi-turn conversations with the agent. -::: +The response contains an `ArtifactUploadEvent` with references to all uploaded +files. This event becomes part of the session history, making the agent aware +of the available files: + + diff --git a/www/docs/agents/tools.md b/www/docs/agents/tools.md index 7b76fe611..1eb66144d 100644 --- a/www/docs/agents/tools.md +++ b/www/docs/agents/tools.md @@ -6,6 +6,16 @@ sidebar_label: Tools import CodePanel from '@site/src/theme/CodePanel'; +Tools provide agents with capabilities to interact with data and external +systems. An agent uses the conversational context and its instructions to +decide which tools to call, and how use the tools' responses to respond to +the user's query. + +Vectara offers a number of useful tools out-of-the-box, but you can also +build your own. For a complete list of available tools, refer to the +[Tools API docs](/docs/rest-api/tools). + + Tools represent external or internal capabilities that agents can invoke dynamically. They are defined by: @@ -13,23 +23,85 @@ dynamically. They are defined by: * A description of their function. * An input schema describing accepted parameters (in JSON Schema format). * Metadata for categorization. -* Runtime availability (enabled/disabled). +* Runtime availability (enabled or disabled). + +## Searching corpora with tools + +You configure corpus search behavior for Vectara agents using the +`query_configuration` parameter within the `corpora_search` tool. This +parameter uses the same `search` and `generation` object formatting as shown +in [Query API](/docs/api-reference/search-apis/search) and [Advanced Single Corpus Query](/docs/rest-api/query-corpus). Before using this tool, +ensure that you have at least one indexed corpus with data. The LLM cannot +modify these predefined search parameters during +conversation. + +For more details about the different corpus objects, see +[Configure Query Parameters](/docs/api-reference/search-apis/query-configuration). + +## Agent configuration examples + +This example demonstrates a basic configuration. + + + +## Working with artifact-based tools -## Available tools +Some agent tools work with files uploaded to a session's workspace. Rather +than embedding file contents in every request, these tools use artifact references. -The tech preview of Vectara Agents provides the following tools: -* **corpora_search:** Retrieves results from a Vectara corpus or corpora using Retrieval - Augmented Generation (RAG). This tool provides summary and relevant search results using - the same default parameters as the Multiple Corpora Query. -* **web_search:** Retrieves results from the public web. +### Document conversion tool +The document conversion tool extracts content from uploaded files and converts +them to markdown format. It accepts an artifact reference as input and creates +a new artifact containing the markdown output. +Supported file types include: +- PDF documents (`.pdf`) +- Microsoft Word (`.doc`, `.docx`) +- Microsoft PowerPoint (`.ppt`, `.pptx`) +- Images with OCR capability (`.jpg`, `.png`) -## Tool permissions and security +For example ahe tool reads a PDF artifact, converts it to markdown, stores +the result as a new artifact, and returns the new artifact reference to the +agent. -Tools follow the same permission model as the rest of Vectara: +### Structured document indexing tool -1. **API keys**: Tools can only access corpora if the API key has access to the - corpora. -2. **Metadata filtering**: Additional security through metadata filters. -3. **Result limiting**: Control how much data tools can retrieve. +The structured document indexing tool adds content from artifacts to corpora. +It references pre-converted markdown artifacts instead of requiring inline +document content, enabling efficient indexing workflows. When the agent calls +this tool, it references the artifact to index. diff --git a/www/docs/api-reference/agent-apis/create-agent.md b/www/docs/api-reference/agent-apis/create-agent.md index 15182b528..81a5c7d2d 100644 --- a/www/docs/api-reference/agent-apis/create-agent.md +++ b/www/docs/api-reference/agent-apis/create-agent.md @@ -6,74 +6,149 @@ sidebar_label: Create Agent import CodePanel from '@site/src/theme/CodePanel'; -The Create Agent API lets you design and deploy smart AI agents capable of -managing sophisticated workflows, running tool-based actions, and -also keep conversational context across multi-turn dialogues. Using the Model -Context Protocol (MCP), this API enables the development of autonomous digital -workers that combine retrieval-augmented generation with external system -integration. +The Create Agent API lets you design and deploy smart AI agents +capable of managing sophisticated workflows, running tool-based +actions, and maintaining conversations. -By configuring agents with specific tools, behavioral instructions, and model -parameters, enterprises can deploy specialized agents for customer support, -business intelligence, workflow automation, and technical assistance scenarios. -These agents operate as configurable, decision-making entities that can reason -through problems, coordinate multiple tools, and adapt their responses based on -conversation context and available capabilities. +By configuring agents with specific instructions, tools, and model parameters, +enterprises can deploy specialized agents for +customer support, business intelligence, workflow automation, and +technical assistance scenarios. -## What is an agent? +:::tip Create an agent +You can create an agent in the [**Vectara Console**](/docs/console-ui/agents/create-an-agent), or you can use the +API. For more information, check out our [**Agents Quick Start**](/docs/agents/agents-quickstart). +::: -An agent is comprised of three main components of functionality: +## Configure agents -1. **Instructions:** Known as a system prompt in other platforms. -2. **Steps:** The workflow the agent executes. -3. **Tools:** Resources available to resolve steps and instructions. +Each agent is configured as follows: -To use an agent, create a new session (called a _thread_ or _chat_ in other -platforms), and send new inputs to the agent to get responses. +* A unique `key` and `name` following the pattern agt_[*identifier*]. If you do not + provide an agent key, Vectara generates one based on the name automatically. +* A human-readable description. +* Optional instructions (system prompts). +* A list of available tools (referenced by name or ID). + When using the `corpora_search` tool, make sure that you already have access + to a corpus with data. +* Metadata and versioning controls. +* A _first_step_ definition that encompasses optional instructions for the + agent's behavior. + +:::note +Currently, agents execute a single conversational step. The `first_step` name +reflects the platform's future support for multi-step agent workflows. For now, +treat `first_step` as "the step." It's the only step your agent executes. +::: ## Create Agent Request and Response -To create an agent, send a POST request to `/v2/agents`. You specify the -following parameters in the request body: - -- `key` (string, optional): A user provided key that uniquely identifies this agent. - If not provided, one will be auto-generated based on the agent name. Pattern: `[0-9a-zA-Z_-]+$` -- `name` (string, required): The human-readable name of the agent -- `description` (string, optional): Detailed description of agent purpose and capabilities -- `tool_configurations` (object, required): A map of tool configurations available to the agent where: - - **Key:** A user-defined name for the tool configuration (e.g., `customer_search`) - - **Value:** An `AgentToolConfiguration` object with: - - `type` (string, required): Tool configuration type (`mcp`, `corpora_search`, or `web_search`) - - `argument_override` (object, optional): Optional hardcoded arguments for tool calls - - `query_configuration` (object, required for `corpora_search`): User-configurable settings for corpus search -- `model` (object, required): Model configuration for agent reasoning - - `name` (string, required): Model name (e.g., `gpt-4`) - - `parameters` (object, optional): Model-specific parameters like temperature and max_tokens - - `retry_configuration` (object, optional): Retry behavior for LLM interactions - - `enabled` (boolean, optional): Enable or disable retry logic (default: `true`) - - `max_retries` (integer, optional): Maximum retry attempts after initial failure, range 0-10 (default: `3`) - - `initial_backoff_ms` (integer, optional): Initial delay before first retry in milliseconds, range 100-60000 (default: `1000`) - - `max_backoff_ms` (integer, optional): Maximum delay between retries in milliseconds, range 1000-300000 (default: `30000`) - - `backoff_factor` (float, optional): Exponential multiplier for backoff delays, range 1.0-10.0 (default: `2.0`) -- `first_step` (object, required): Initial execution step configuration - - `type` (string, required): Step type (must be `conversational`) - - `instructions` (array, required): List of instruction objects - - Reference instructions: - - `type` (string, required): Must be `reference` - - `id` (string, required): Instruction identifier following pattern `ins_[0-9a-zA-Z_-]+$` - - `version` (integer, optional): Specific instruction version - - Inline instructions: - - `type` (string, required): Must be `inline` - - `name` (string, required): Human-readable instruction name - - `template_type` (string, optional): Must be `velocity` (default) - - `template` (string, required): Instruction template content - - `description` (string, optional): Instruction description - - `output_parser` (object, required): Output parser configuration - - `type` (string, required): Parser type (must be `default`) -- `metadata` (object, optional): Arbitrary key-value pairs for organization and tracking -- `enabled` (boolean, optional): Whether agent is active upon creation (defaults to `true`) - -The response includes the complete agent configuration with system-generated fields including the unique agent key, creation timestamp, and update timestamp. +To create an agent, send a POST request to `/v2/agents` with the +following configuration sections. For a list of all agent configuration +parameters, see [Create Agent API Definition](/docs/api-reference/agent-apis/create-agent). + +### Basic Configuration + +Core agent identification and metadata: + +* `key` (string, optional): A user provided key that uniquely + identifies this agent. If not provided, one will be auto-generated + based on the agent name. Pattern: `[0-9a-zA-Z_-]+$` +* `name` (string, required): The human-readable name of the agent +* `description` (string, optional): Detailed description of agent + purpose and capabilities +* `metadata` (object, optional): Arbitrary key-value pairs for + organization and tracking +* `enabled` (boolean, optional): Whether agent is active upon creation + (defaults to `true`) + +### Tool Configurations + +The `tool_configurations` parameter defines which capabilities the +agent can use. It's a map where each entry pairs a configuration name +with tool settings: + +* **Key:** A user-defined name for the tool configuration (e.g., + `customer_search`, `web_search`). This name is how the agent refers + to this specific tool configuration in events and logs. +* **Value:** An `AgentToolConfiguration` object that specifies: + * `type` (string, required): The tool type - one of: + * `corpora_search`: Query Vectara corpora using RAG + * `web_search`: Search the web for current information + * `mcp`: Connect to external Model Context Protocol servers + * `lambda`: Execute custom Python functions (user-defined tools) + * `structured_indexing`: Index structured documents into Vectara + corpora + * `argument_override` (object, optional): Hardcoded arguments that + override LLM-provided values. When specified, the LLM cannot + change these parameters. Supports dynamic references using + `{"$ref": "path.to.value"}` syntax (e.g., + `{"$ref": "session.metadata.customer_id"}`) + * `query_configuration` (object, required for `corpora_search`): + Query settings including search parameters, generation settings, + and reranking configuration - not exposed to the LLM + +### Model Configuration + +The `model` parameter controls the LLM used for agent reasoning: + +* `name` (string, required): Model name (e.g., `gpt-4`) +* `parameters` (object, optional): Model-specific parameters like + temperature and max_tokens +* `retry_configuration` (object, optional): Retry behavior for LLM + interactions + * `enabled` (boolean, optional): Enable or disable retry logic + (default: `true`) + * `max_retries` (integer, optional): Maximum retry attempts after + initial failure, range 0-10 (default: `3`) + * `initial_backoff_ms` (integer, optional): Initial delay before + first retry in milliseconds, range 100-60000 (default: `1000`) + * `max_backoff_ms` (integer, optional): Maximum delay between + retries in milliseconds, range 1000-300000 (default: `30000`) + * `backoff_factor` (float, optional): Exponential multiplier for + backoff delays, range 1.0-10.0 (default: `2.0`) + +### Step Configuration + +The `first_step` parameter defines the agent's workflow and behavior: + +* `type` (string, required): Step type (must be `conversational` - + the only currently supported type) +* `instructions` (array, required): An ordered list of instructions + that guide the agent's behavior. Instructions use the Apache + Velocity template language and can reference context variables. You + can mix reference and inline instructions: + * **Reference instructions** - Reusable instructions stored + separately that can be shared across multiple agents: + * `type` (string, required): Must be `reference` + * `id` (string, required): The instruction's unique identifier + (pattern: `ins_[0-9a-zA-Z_-]+$`) + * `version` (integer, optional): Specific version number to use. + If omitted, the latest version is used. Note: When a referenced + instruction is updated, agents must be explicitly updated to + use the new version. + * **Inline instructions** - Instructions defined directly within + the agent configuration: + * `type` (string, required): Must be `inline` + * `name` (string, required): Human-readable name for this + instruction + * `template_type` (string, optional): Template language to use + (must be `velocity`, which is the default) + * `template` (string, required): The instruction content using + Velocity template syntax. Use `${variableName}` to reference + dynamic values. + * `description` (string, optional): Optional description + explaining the instruction's purpose +* `output_parser` (object, required): Configures how the agent's + output is parsed and returned + * `type` (string, required): Parser type (currently only `default` + is supported, which uses native LLM tool calling) + +### Response + +The response includes the complete agent configuration with +system-generated fields including the unique agent key, creation +timestamp, and update timestamp. ### Example Request @@ -133,7 +208,7 @@ The response includes the complete agent configuration with system-generated fie { "type": "inline", "name": "Additional Guidelines", - "template": "Always be polite and professional. Today's date is currentDate.", + "template": "Always be polite and professional. Today's date is ${currentDate}.", "template_type": "velocity" } ], @@ -161,9 +236,9 @@ The response includes the complete agent configuration with system-generated fie code: `{ "key": "customer_support", "name": "Customer Support Agent", - "description": "AI agent specialized in handling customer support inquiries using company documentation", - "tools": { - "tol_customer_search": { + "description": "AI agent specialized in handling customer support inquiries using company documentation", + "tool_configurations": { + "customer_search": { "type": "corpora_search", "argument_override": { "query": "customer support documentation" @@ -180,7 +255,7 @@ The response includes the complete agent configuration with system-generated fie "save_history": true } }, - "tol_web_search": { + "web_search": { "type": "web_search", "argument_override": { "limit": 5 @@ -212,7 +287,7 @@ The response includes the complete agent configuration with system-generated fie { "type": "inline", "name": "Additional Guidelines", - "template": "Always be polite and professional. Today's date is currentDate.", + "template": "Always be polite and professional. Today's date is ${currentDate}.", "template_type": "velocity" } ], @@ -232,9 +307,137 @@ The response includes the complete agent configuration with system-generated fie layout="stacked" /> + +### Argument override option + +Each agent also has an optional `argument_override` option that lets you +specify hardcoded arguments for specific search calls. Use this option to +override schema-defined fields like `query` or `limit` for enforcing fixed +behavior. + + + + +### Retry configuration + +When agents interact with LLMs, transient failures may occur that interrupt +the conversation flow, including network timeouts, temporary server issues, +or reaching API rate limits. Without a retry mechanism, these temporary +issues cause your agent to fail immediately, resulting in a poor user +experience. + +Vectara provides a retry configuration option for agents which detects these +recoverable failures and retries the request with exponential backoff +automatically. + +The `RetryConfiguration` object controls the retry behavior for your agent's +interactions with the LLM. You define these settings when creating or +updating your agent model, and they apply to all LLM requests made by that +agent. + +### Retry configuration parameters + +- **enabled**: The boolean flag to enable or disable retry logic. + - Default: `true` +- **max_retries**: The maximum number of retry attempts after the initial failure. + - Range: 0-10 + - Default: `3` +- **initial_backoff_ms**: The initial delay in milliseconds before the first retry. + - Range: 100-60000ms + - Default: `1000ms` +- **max_backoff_ms**: The maximum delay in milliseconds between retries. + - Range: 1000-300000ms + - Default: `30000ms` +- **backoff_factor**: The exponential multiplier for calculating backoff delays. + - Range: 1.0-10.0 + - Default: `2.0` + + +### Exponential backoff + +Exponential backoff progressively increases the delay between retry attempts +to avoid overwhelming a recovering service. For example, with default +settings (initial: 1000ms, factor: 2.0, max: 30000ms): + +- Attempt 1: 1000ms delay +- Attempt 2: 2000ms delay +- Attempt 3: 4000ms delay +- Attempt 4: 8000ms delay + +The delay continues to grow exponentially until it reaches the +`max_backoff_ms` value, at which point it remains constant for any remaining +retry attempts. + +## Example agent definition + +This example shows a basic customer support agent configured with corpus +search capabilities and inline instructions. The agent demonstrates the core +components: tool configurations for searching support tickets, and a +conversational first step with behavior guidelines. + + + + ## Error Responses -The API returns standard HTTP error codes with detailed error information: +The API returns standard HTTP error codes with detailed error +information: | HTTP Code | Error Code | Description | |-----------|------------|-------------| diff --git a/www/docs/api-reference/agent-apis/event/create-agent-event.md b/www/docs/api-reference/agent-apis/event/create-agent-event.md index 4e86c641d..c0b6230f8 100644 --- a/www/docs/api-reference/agent-apis/event/create-agent-event.md +++ b/www/docs/api-reference/agent-apis/event/create-agent-event.md @@ -6,13 +6,16 @@ sidebar_label: Interact with an Agent import CodePanel from '@site/src/theme/CodePanel'; -The Interact with an Agent API enables you to create new inputs to an agent to interact with it. This API serves as the primary interface for conversational interactions and represents the core mechanism through which users communicate with AI agents. +The Interact with an Agent API enables you to chat with an agent. -When you send an input to an agent, it triggers agent processing, reasoning, tool execution, and response generation within the context of an agent session. +When you send an input to an agent, it triggers agent processing, +reasoning, tool execution, and response generation within the context +of an agent session. ## Interact with an Agent Request and Response -To interact with an agent, send a POST request to `/v2/agents/{agent_key}/sessions/{session_key}/events`. You specify the following parameters: +To interact with an agent, send a POST request to +`/v2/agents/{agent_key}/sessions/{session_key}/events`. You specify the following parameters: - `agent_key` (string, required): Agent identifier in the URL path following pattern `[0-9a-zA-Z_-]+$` - `session_key` (string, required): Session identifier in the URL path following pattern `[0-9a-zA-Z_-]+$` @@ -161,6 +164,19 @@ For streaming responses, additional event types include: - `error`: Stream error - `end`: Stream completion +### Artifacts in Agent Workspaces + +Each agent session includes its own workspace that stores uploaded and +generated files, known as **artifacts**. + +Artifacts persist for the session’s duration and enable the agent to reuse +files across multiple steps in a workflow. + +For example, a user might upload a PDF for analysis, and the agent can +convert, summarize, and index that same file without requiring reupload. +Artifacts remain session-bound for privacy and are deleted automatically +when the session expires. + ## Error Responses The API returns standard HTTP error codes with detailed error information: diff --git a/www/docs/api-reference/agent-apis/event/get-agent-event.md b/www/docs/api-reference/agent-apis/event/get-agent-event.md index d44bf0192..032530409 100644 --- a/www/docs/api-reference/agent-apis/event/get-agent-event.md +++ b/www/docs/api-reference/agent-apis/event/get-agent-event.md @@ -4,21 +4,29 @@ title: Get Agent Event API Definition sidebar_label: Get Agent Event --- -# Get Agent Event API Definition +The Get Agent Event API enables you to retrieve detailed information about a +specific interaction event within an agent session, providing comprehensive +visibility into individual steps of agent processing, tool executions, or +user inputs. -The Get Agent Event API enables you to retrieve detailed information about a specific interaction event within an agent session, providing comprehensive visibility into individual steps of agent processing, tool executions, or user inputs. This API is crucial for debugging specific agent behaviors, analyzing tool performance, and understanding the granular details of agent reasoning processes. - -Development teams and quality assurance analysts use this API to inspect specific events during troubleshooting, analyze tool execution results for optimization, verify agent reasoning patterns, and extract detailed information about individual interactions for performance analysis and conversation quality assessment. +Use this API to inspect specific events during troubleshooting, analyze tool +execution results for optimization, verify agent reasoning patterns, and extract +detailed information about individual interactions for performance analysis and +conversation quality assessment. ## Get Agent Event Request and Response -To retrieve an agent event, send a GET request to `/v2/agents/{agent_key}/sessions/{session_id}/events/{event_id}`. You specify the following parameters in the URL path: +To retrieve an agent event, send a GET request to +`/v2/agents/{agent_key}/sessions/{session_id}/events/{event_id}`. You specify +the following parameters in the URL path: - `agent_key` (string, required): Agent identifier following the pattern `agt_[0-9a-zA-Z_-]+$` - `session_key` (string, required): Session identifier following the pattern `ase_[0-9a-zA-Z_-]+$` - `event_id` (string, required): Event identifier following the pattern `aev_[0-9a-zA-Z_-]+$` -The response includes the complete event details with all associated data, including event type, content, timestamps, and any tool-specific information depending on the event type. +The response includes the complete event details with all associated data, +including event type, content, timestamps, and any tool-specific information +depending on the event type. ### Example Request @@ -71,4 +79,4 @@ The API returns standard HTTP error codes with detailed error information: | 404 | `agent_not_found` | Agent with the specified `agent_key` does not exist | | 404 | `session_not_found` | Session with the specified ID does not exist | | 404 | `event_not_found` | Event with the specified ID does not exist | -| 429 | `rate_limit_exceeded` | Request rate limit exceeded | \ No newline at end of file +| 429 | `rate_limit_exceeded` | Request rate limit exceeded | diff --git a/www/docs/api-reference/agent-apis/event/list-agent-events.md b/www/docs/api-reference/agent-apis/event/list-agent-events.md index 174856e31..0219f69ec 100644 --- a/www/docs/api-reference/agent-apis/event/list-agent-events.md +++ b/www/docs/api-reference/agent-apis/event/list-agent-events.md @@ -4,22 +4,28 @@ title: List Agent Events API Definition sidebar_label: List Agent Events --- -# List Agent Events API Definition +The List Agent Events API enables you to retrieve all interactions +within a specific agent session, providing visibility into +conversation flow, agent reasoning, tool executions, and response generation. -The List Agent Events API enables you to retrieve a chronological sequence of all interactions and processing activities within a specific agent session, providing complete visibility into conversation flow, agent reasoning, tool executions, and response generation. This API is essential for conversation analysis, debugging agent behavior, and maintaining detailed audit trails of agent interactions. - -Organizations use this API to analyze conversation patterns for quality assurance, troubleshoot agent behavior during development, generate conversation transcripts for compliance purposes, and extract interaction data for training and optimization of agent performance across their enterprise AI deployments. +Use this API to analyze conversation patterns for quality assurance, troubleshoot +agent behavior during development, generate conversation transcripts for compliance +purposes, and extract interaction data for training and agent optimization. ## List Agent Events Request and Response -To list agent events, send a GET request to `/v2/agents/{agent_key}/sessions/{session_key}/events`. You specify the following parameters: +To list agent events, send a GET request to +`/v2/agents/{agent_key}/sessions/{session_key}/events`. You specify the following +parameters: - `agent_key` (string, required): Agent identifier in the URL path following pattern `agt_[0-9a-zA-Z_-]+$` - `session_key` (string, required): Session identifier in the URL path following pattern `ase_[0-9a-zA-Z_-]+$` - `limit` (integer, optional): Maximum number of events to return (default: 20, maximum: 100) - `page_key` (string, optional): Pagination token for retrieving subsequent pages of results -The response includes an array of event objects in chronological order, representing the complete interaction history within the specified session, along with pagination metadata for accessing additional events when available. +The response includes an array of event objects in chronological order, representing +the complete interaction history within the specified session, along with pagination +metadata for accessing additional events when available. ### Example Request @@ -107,4 +113,4 @@ The API returns standard HTTP error codes with detailed error information: | 403 | `forbidden` | Insufficient permissions for accessing events in this session | | 404 | `agent_not_found` | Agent with the specified `agent_key` does not exist | | 404 | `session_not_found` | Session with the specified `session_key` does not exist | -| 429 | `rate_limit_exceeded` | Request rate limit exceeded | \ No newline at end of file +| 429 | `rate_limit_exceeded` | Request rate limit exceeded | diff --git a/www/docs/api-reference/agent-apis/instruction/create-instruction.md b/www/docs/api-reference/agent-apis/instruction/create-instruction.md index f46fd784a..b43e8e6db 100644 --- a/www/docs/api-reference/agent-apis/instruction/create-instruction.md +++ b/www/docs/api-reference/agent-apis/instruction/create-instruction.md @@ -4,15 +4,21 @@ title: Create Instruction API Definition sidebar_label: Create Instruction --- -import CodePanel from '@site/src/theme/CodePanel'; +import CodePanel from '@site/src/theme/CodePanel'; -The Create Instruction API enables you to create reusable sets of behavioral guidelines that shape how AI agents reason, respond, and interact with users and tools. Instructions are fundamental to ensuring that agents operate within enterprise policies, follow best practices, and maintain a consistent tone and personality across all interactions. +The Create Instruction API enables you to create reusable sets of behaviors to +tell agents how to reason, respond, and interact with users and tools. -Organizations use this API to define standardized operational protocols, enforce compliance with regulatory requirements, and customize agent behavior to align with specific business use cases, such as customer support, financial analysis, or internal workflow automation. + +Organizations use this API to define standardized operational protocols, +enforce compliance with regulatory requirements, and customize agent behavior +to align with specific business use cases, such as customer support, financial +analysis, or internal workflow automation. ## Create Instruction Request and Response -To create an instruction, send a POST request to `/v2/instructions`. You specify the following parameters in the request body: +To create an instruction, send a POST request to `/v2/instructions`. You +specify the following parameters in the request body: - `name` (string, required): A human-readable name for the instruction. - `description` (string, optional): A detailed description of the instruction's purpose and intended use. @@ -20,12 +26,14 @@ To create an instruction, send a POST request to `/v2/instructions`. You specify - `enabled` (boolean, optional): Whether the instruction should be enabled upon creation (defaults to `true`). - `metadata` (object, optional): Arbitrary metadata for tracking, versioning, or categorization. -The response includes the full definition of the newly created instruction, including system-generated fields such as `id`, `version`, `created_at`, and `updated_at`. +The response includes the full definition of the newly created instruction, +including system-generated fields such as `id`, `version`, `created_at`, and +`updated_at`. ### Example Request +You can configure instructions for an agent in two ways: **inline** or +**shared**. + +## Inline Instructions + +You define inline instructions when you configure an agent. These instructions +are specific to that agent and best for situations that do not require reuse. + +- **Type**: To specify an inline instruction, set the `type` field to `"inline"`. +- **Lifecycle**: An inline instruction is automatically deleted if the agent it + belongs to is deleted. + + + +## Shared (Reference) Instructions + +You can create shared instructions as independent, versioned entities for reuse +across multiple agents. This is ideal for standardizing behavior, such as +enforcing brand voice or defining common workflows. + +A shared instruction consists of the following: +* A unique ID (`ins_12345`). +* A `name` and `description`. +* A `prompt` template. +* Optional `metadata` for organization. +* A `version` for tracking updates. + +To use a shared instruction, set the `type` field to `"reference"` +and provide the instruction's unique `id`. + +:::note +When you update a shared instruction, this creates a new version of that +instruction. To use the new version, you must update any agents that +reference the instruction. If you do not specify a version, the agent uses +the latest one. +::: + + + + + ## Error Responses The API returns standard HTTP error codes with detailed error information: diff --git a/www/docs/api-reference/agent-apis/instruction/test-instruction.md b/www/docs/api-reference/agent-apis/instruction/test-instruction.md index 0755ba687..8cf6c2b69 100644 --- a/www/docs/api-reference/agent-apis/instruction/test-instruction.md +++ b/www/docs/api-reference/agent-apis/instruction/test-instruction.md @@ -55,6 +55,13 @@ There is no request body for this endpoint. If the instruction template is valid layout="stacked" /> +### Custom variables + +You can define custom variables and pass them when testing instructions using +the Test Instruction API. This enables you to validate how your templates +render with different context values before deploying them in production agents. + + ## Error Responses The API returns standard HTTP error codes with detailed error information: diff --git a/www/docs/api-reference/agent-apis/session/create-agent-session.md b/www/docs/api-reference/agent-apis/session/create-agent-session.md index 388bd678c..b2a26ce54 100644 --- a/www/docs/api-reference/agent-apis/session/create-agent-session.md +++ b/www/docs/api-reference/agent-apis/session/create-agent-session.md @@ -6,23 +6,39 @@ sidebar_label: Create Agent Session import CodePanel from '@site/src/theme/CodePanel'; -The Create Agent Session API enables you to initialize a new conversational session between users and AI agents, establishing the contextual container required for stateful, multi-turn interactions. This API is fundamental to deploying conversational AI experiences that maintain memory, track interaction history, and provide continuity across extended dialogues with enterprise users. +The Create Agent Session API enables you to initialize a new +chat with an agent, establishing the +contextual container required for multi-turn interactions. -Organizations use this API to create customer support sessions, internal process automation workflows, business intelligence conversations, and technical assistance interactions where context preservation and session-based tracking are essential for delivering personalized and effective AI-powered experiences. +Use this API to create customer support sessions, +internal process automation workflows, business intelligence +conversations, and technical assistance interactions where context +preservation and session-based tracking are essential. ## Create Agent Session Request and Response -To create an agent session, send a POST request to `/v2/agents/{agent_key}/sessions`. You specify the following parameters: +To create an agent session, send a POST request to +`/v2/agents/{agent_key}/sessions`. You specify the following +parameters: -- `agent_key` (string, required): Agent identifier in the URL path following pattern `[0-9a-zA-Z_-]+$` +- `agent_key` (string, required): Agent identifier in the URL path + following pattern `[0-9a-zA-Z_-]+$` - Request body parameters: - - `key` (string, optional): A user provided key that uniquely identifies this session. If not provided, one will be auto-generated based on the session name. Pattern: `[0-9a-zA-Z_-]+$` + - `key` (string, optional): A user provided key that uniquely + identifies this session. If not provided, one will be + auto-generated based on the session name. Pattern: + `[0-9a-zA-Z_-]+$` - `name` (string, required): Human-readable name for the session - - `description` (string, optional): Optional description of the session purpose or context - - `metadata` (object, optional): Arbitrary metadata associated with the session for tracking and organization - - `enabled` (boolean, optional): Whether the session should be enabled upon creation (defaults to `true`) + - `description` (string, optional): Optional description of the + session purpose or context + - `metadata` (object, optional): Arbitrary metadata associated with + the session for tracking and organization + - `enabled` (boolean, optional): Whether the session should be + enabled upon creation (defaults to `true`) -The response includes the complete session configuration with system-generated fields including the unique session key, associated agent key, and creation timestamp. +The response includes the complete session configuration with +system-generated fields including the unique session key, associated +agent key, and creation timestamp. ### Example Request @@ -76,9 +92,145 @@ The response includes the complete session configuration with system-generated f layout="stacked" /> +## Session keys + +When issuing API requests to retrieve or chat with a session, you need to +identify _which_ session you're referring to. You do this with the session's +`key`, which is assigned when the session is first created. If you don't specify +the `key` when you create the session, Vectara will automatically generate one +for you. If you prefer your session keys to convey meaning, you can define +the `key` as part of the request. + + +## Agent events + +Each session contains one or more events, representing individual interactions +and system activities within the conversation: + +- **Input message events**: User input with text content +- **Thinking events**: Agent reasoning and chain-of-thought processes +- **Tool input/output events**: Tool execution with parameters and results +- **Agent output events**: Final agent responses to user input + +Events support both synchronous and streaming delivery, enabling real-time +conversation experiences with progressive response building. + +### Example session and event + + + +### Session workflow example + +Here's how to create a session and start chatting with an agent: + + + +:::tip +Sessions persist conversation history, so subsequent messages in the same +session will have context of previous interactions. This enables natural, +multi-turn conversations with the agent. +::: + +### Working with Artifacts in Sessions + +Artifacts represent files uploaded or generated within an agent session. They +provide a persistent workspace where agents and users can share files +throughout a conversation. + +When a user uploads a file with a multipart request, the file is stored as an +**artifact** and referenced in an `ArtifactUploadEvent`. Each artifact has a +unique `artifact_id` and includes metadata such as its filename, MIME type, +and size. + +Artifacts remain available for the duration of the session and can be accessed +by agent tools for processing, conversion, or indexing. Agents and tools can +also create new artifacts. For example, the document conversion tool might +generate a Markdown artifact from an uploaded PDF. + +- Artifacts are **session-scoped** and cannot be accessed from other sessions. +- Use the `artifact_id` to reference + artifacts in subsequent tool calls. +- Artifacts have a configurable **time-to-live (TTL)** and are removed + automatically when they expire or when the session ends. + ## Error Responses -The API returns standard HTTP error codes with detailed error information: +The API returns standard HTTP error codes with detailed error +information: | HTTP Code | Error Code | Description | |-----------|------------|-------------| diff --git a/www/docs/api-reference/agent-apis/session/delete-agent-session.md b/www/docs/api-reference/agent-apis/session/delete-agent-session.md index a88289255..294e76932 100644 --- a/www/docs/api-reference/agent-apis/session/delete-agent-session.md +++ b/www/docs/api-reference/agent-apis/session/delete-agent-session.md @@ -4,20 +4,25 @@ title: Delete Agent Session API Definition sidebar_label: Delete Agent Session --- -# Delete Agent Session API Definition +The Delete Agent Session API enables you to permanently remove a +session and all its associated events and interaction history. -The Delete Agent Session API enables you to permanently remove a conversational session and all its associated events and interaction history from the Vectara platform. This API supports session lifecycle management, privacy compliance, and resource cleanup by providing controlled deletion capabilities for completed or inactive conversations. -Organizations use this API to comply with data retention policies, clean up test and development sessions, remove sensitive conversations upon customer request, and maintain organized session inventories by removing completed interactions that are no longer needed for operational or analytical purposes. +Use this API to comply with data retention policies, clean up test and +development sessions, remove sensitive conversations upon customer request. ## Delete Agent Session Request and Response -To delete an agent session, send a DELETE request to `/v2/agents/{agent_key}/sessions/{session_key}`. You specify the following parameters in the URL path: +To delete an agent session, send a DELETE request to +`/v2/agents/{agent_key}/sessions/{session_key}`. You specify the following parameters +in the URL path: - `agent_key` (string, required): Agent identifier following the pattern `agt_[0-9a-zA-Z_-]+$` - `session_key` (string, required): Session identifier following the pattern `ase_[0-9a-zA-Z_-]+$` -The response returns HTTP status 204 (No Content) on successful deletion with no response body, indicating that the session and all associated events have been permanently removed from the system. +The response returns HTTP status 204 (No Content) on successful deletion with +no response body, indicating that the session and all associated events have +been permanently removed from the system. ### Example Request @@ -42,4 +47,4 @@ The API returns standard HTTP error codes with detailed error information: | 403 | `forbidden` | Insufficient permissions for deleting this session | | 404 | `agent_not_found` | Agent with the specified `agent_key` does not exist | | 404 | `session_not_found` | Session with the specified `session_key` does not exist | -| 429 | `rate_limit_exceeded` | Request rate limit exceeded | \ No newline at end of file +| 429 | `rate_limit_exceeded` | Request rate limit exceeded | diff --git a/www/docs/api-reference/agent-apis/session/get-agent-session.md b/www/docs/api-reference/agent-apis/session/get-agent-session.md index 81a007feb..d130abe81 100644 --- a/www/docs/api-reference/agent-apis/session/get-agent-session.md +++ b/www/docs/api-reference/agent-apis/session/get-agent-session.md @@ -4,20 +4,26 @@ title: Get Agent Session API Definition sidebar_label: Get Agent Session --- -# Get Agent Session API Definition +The Get Agent Session API enables you to retrieve detailed information about a +specific conversational session, including its configuration, metadata, and +current status within an agent's interaction history. -The Get Agent Session API enables you to retrieve detailed information about a specific conversational session, including its configuration, metadata, and current status within an agent's interaction history. This API is essential for session monitoring, conversation analysis, and troubleshooting agent behavior during multi-turn interactions. - -Development teams and support administrators use this API to inspect session contexts during debugging, analyze conversation metadata for optimization insights, verify session configurations before event creation, and maintain detailed records of customer interactions for quality assurance and compliance purposes. +Use this API to inspect session contexts during debugging, analyze conversation +metadata for optimization insights, verify session configurations before event +creation, and maintain detailed records of customer interactions for quality +assurance and compliance purposes. ## Get Agent Session Request and Response -To retrieve an agent session, send a GET request to `/v2/agents/{agent_key}/sessions/{session_key}`. You specify the following parameters in the URL path: +To retrieve an agent session, send a GET request to +`/v2/agents/{agent_key}/sessions/{session_key}`. You specify the following parameters in the URL path: - `agent_key` (string, required): Agent identifier following the pattern `agt_[0-9a-zA-Z_-]+$` - `session_key` (string, required): Session identifier following the pattern `ase_[0-9a-zA-Z_-]+$` -The response includes the complete session configuration with all metadata, status information, and timestamps as configured during session creation or subsequent updates. +The response includes the complete session configuration with all metadata, +status information, and timestamps as configured during session creation or +subsequent updates. ### Example Request @@ -64,4 +70,4 @@ The API returns standard HTTP error codes with detailed error information: | 403 | `forbidden` | Insufficient permissions for accessing this session | | 404 | `agent_not_found` | Agent with the specified `agent_key` does not exist | | 404 | `session_not_found` | Session with the specified `session_key` does not exist | -| 429 | `rate_limit_exceeded` | Request rate limit exceeded | \ No newline at end of file +| 429 | `rate_limit_exceeded` | Request rate limit exceeded | diff --git a/www/docs/api-reference/agent-apis/session/list-agent-sessions.md b/www/docs/api-reference/agent-apis/session/list-agent-sessions.md index 8cdf375bc..8a22a97c0 100644 --- a/www/docs/api-reference/agent-apis/session/list-agent-sessions.md +++ b/www/docs/api-reference/agent-apis/session/list-agent-sessions.md @@ -6,11 +6,13 @@ sidebar_label: List Agent Sessions import CodePanel from '@site/src/theme/CodePanel'; -# List Agent Sessions API Definition +The List Agent Sessions API enables you to retrieve a list of conversational +sessions associated with a specific AI agent. -The List Agent Sessions API enables you to retrieve a paginated collection of conversational sessions associated with a specific AI agent, providing essential visibility into agent usage patterns, active conversations, and session management across your enterprise deployment. This API supports operational monitoring, user analytics, and administrative oversight of agent interactions. - -Organizations use this API to monitor customer engagement levels, track support case volumes, analyze conversation patterns for training and optimization, and maintain operational dashboards that provide real-time visibility into their AI agent ecosystem's performance and utilization. +Use this API to monitor customer engagement levels, track support case volumes, +analyze conversation patterns for training and optimization, and maintain +operational dashboards that provide real-time visibility into their AI agent +ecosystem's performance and utilization. ## List Agent Sessions Request and Response diff --git a/www/docs/api-reference/agent-apis/session/update-agent-session.md b/www/docs/api-reference/agent-apis/session/update-agent-session.md index d9c5db402..17bdfa8d2 100644 --- a/www/docs/api-reference/agent-apis/session/update-agent-session.md +++ b/www/docs/api-reference/agent-apis/session/update-agent-session.md @@ -4,20 +4,26 @@ title: Update Agent Session API Definition sidebar_label: Update Agent Session --- -# Update Agent Session API Definition +The Update Agent Session API enables you to modify session configuration and +metadata. -The Update Agent Session API enables you to modify session metadata, descriptions, and operational status during active conversations, supporting dynamic session management and real-time updates to conversation context. This API is crucial for maintaining accurate session tracking as conversations evolve and business context changes. - -Organizations use this API to update customer information as it becomes available, adjust session priority levels based on issue escalation, modify session metadata for better categorization and reporting, and manage session lifecycles by enabling or disabling sessions based on operational requirements. +Use this API to update information as it becomes available, and modify session +metadata for better categorization and reporting. ## Update Agent Session Request and Response -To update an agent session, send a PATCH request to `/v2/agents/{agent_key}/sessions/{session_key}`. You specify the agent and session identifiers in the URL path and include only the fields you want to modify in the request body: +To update an agent session, send a PATCH request to +`/v2/agents/{agent_key}/sessions/{session_key}`. You specify the agent and +session identifiers in the URL path and include only the fields you want to +modify in the request body: -- `agent_key` (string, required): Agent identifier in the URL path following pattern `agt_[0-9a-zA-Z_-]+$` -- `session_key` (string, required): Session identifier in the URL path following pattern `ase_[0-9a-zA-Z_-]+$` +- `agent_key` (string, required): Agent identifier in the URL path following + pattern `agt_[0-9a-zA-Z_-]+$` +- `session_key` (string, required): Session identifier in the URL path following + pattern `ase_[0-9a-zA-Z_-]+$` - `description` (string, optional): Updated session description or context -- `metadata` (object, optional): Updated session metadata (replaces existing metadata completely) +- `metadata` (object, optional): Updated session metadata (replaces existing + metadata completely) - `enabled` (boolean, optional): Updated session enabled status The response includes the complete updated session configuration reflecting all changes applied during the update operation. diff --git a/www/docs/api-reference/agent-apis/tool-server/create-tool-server.md b/www/docs/api-reference/agent-apis/tool-server/create-tool-server.md index 312710cf3..601e491cb 100644 --- a/www/docs/api-reference/agent-apis/tool-server/create-tool-server.md +++ b/www/docs/api-reference/agent-apis/tool-server/create-tool-server.md @@ -6,26 +6,35 @@ sidebar_label: Create Tool Server import CodePanel from '@site/src/theme/CodePanel'; -The Create Tool Server API enables you to register Model Context Protocol (MCP) compliant servers that expose tools for use by AI agents. Tool servers act as bridges between your enterprise systems and the Vectara platform, making capabilities like database queries, API integrations, and custom business logic available to agents through a standardized protocol. - -This API is fundamental to extending agent capabilities beyond built-in functions, allowing organizations to expose their internal systems, third-party integrations, and custom tools in a secure, managed way that maintains governance and access control. +The Create Tool Server API enables you to register Model Context Protocol +(MCP) compliant servers that expose tools for use by AI agents. Tool servers +act as bridges between your enterprise systems and the Vectara platform, +making capabilities like database queries, API integrations, and custom +business logic available to agents through a standardized protocol. ## Create Tool Server Request and Response -To create a tool server, send a POST request to `/v2/tool_servers`. You specify the following parameters in the request body: - -- `name` (string, required): The human-readable name of the tool server -- `type` (string, required): Must be `mcp` (Model Context Protocol) -- `description` (string, optional): A detailed description of what this tool server provides -- `uri` (string, required): The URI of the tool server (must be a valid URI) -- `transport` (string, required): Transport protocol, must be `sse` (Server-Sent Events) -- `headers` (object, optional): HTTP headers to include when connecting to the server -- `auth` (object, optional): Authentication configuration for connecting to the tool server - - Various auth types supported (see Authentication documentation) -- `enabled` (boolean, optional): Whether the server is enabled upon creation (defaults to `true`) -- `metadata` (object, optional): Arbitrary metadata for tracking and organization - -The response includes the complete tool server configuration with a system-generated ID and timestamps. +To create a tool server, send a POST request to `/v2/tool_servers`. You +specify the following parameters in the request body: + +- `name` (string, required): The human-readable name of the tool server. +- `type` (string, required): Must be `mcp` (Model Context Protocol). +- `description` (string, optional): A detailed description of what this tool + server provides. +- `uri` (string, required): The URI of the tool server (must be a valid URI). +- `transport` (string, required): Transport protocol, must be `sse` (Server-Sent + Events). +- `headers` (object, optional): HTTP headers to include when connecting to the + server. +- `auth` (object, optional): Authentication configuration for connecting to the + tool server. + - Various auth types supported (see Authentication documentation). +- `enabled` (boolean, optional): Whether the server is enabled upon creation + (defaults to `true`). +- `metadata` (object, optional): Arbitrary metadata for tracking and organization. + +The response includes the complete tool server configuration with a system-generated +ID and timestamps. ### Example Request diff --git a/www/docs/api-reference/agent-apis/tool-server/delete-tool-server.md b/www/docs/api-reference/agent-apis/tool-server/delete-tool-server.md index ecbf4f108..2d0a0eb64 100644 --- a/www/docs/api-reference/agent-apis/tool-server/delete-tool-server.md +++ b/www/docs/api-reference/agent-apis/tool-server/delete-tool-server.md @@ -6,13 +6,19 @@ sidebar_label: Delete Tool Server import CodePanel from '@site/src/theme/CodePanel'; -The Delete Tool Server API enables you to permanently remove a Model Context Protocol (MCP) server from your Vectara account. This action cascades to all associated tools, making them unavailable for agent configuration. This API supports lifecycle management, decommissioning of deprecated integrations, and cleanup of test or development servers. +The Delete Tool Server API enables you to permanently remove a Model Context +Protocol (MCP) server from your Vectara account. This action cascades to all +associated tools, making them unavailable for agent configuration. This API +supports lifecycle management, decommissioning of deprecated integrations, +and cleanup of test or development servers. -This operation is irreversible and should be used with caution, particularly for production servers that may be referenced by active agent configurations. +This operation is irreversible and should be used with caution, particularly for +production servers that may be referenced by active agent configurations. ## Delete Tool Server Request and Response -To delete a tool server, send a DELETE request to `/v2/tool_servers/{tool_server_id}`. You specify the following parameter: +To delete a tool server, send a DELETE request to `/v2/tool_servers/{tool_server_id}`. +You specify the following parameter: - `tool_server_id` (string, required): Tool server identifier in the URL path following pattern `tsr_[0-9a-zA-Z_-]+$` @@ -42,15 +48,6 @@ The API returns a 204 No Content response on successful deletion. layout="stacked" /> -## Cascading Effects - -When you delete a tool server: -1. The server registration is permanently removed -2. All tools associated with the server become unavailable -3. Agents configured with these tools may experience errors -4. Tool configurations referencing these tools remain but become non-functional -5. Active sessions using these tools continue but cannot invoke the deleted tools - ## Error Responses The API returns standard HTTP error codes with detailed error information: @@ -63,14 +60,3 @@ The API returns standard HTTP error codes with detailed error information: | 409 | `server_in_use` | Cannot delete server with tools in active use | | 429 | `rate_limit_exceeded` | Delete rate limit exceeded | -## Best Practices - -- List all tools from the server before deletion to understand impact -- Disable the server first and monitor for issues before deletion -- Update agent configurations to remove references to server tools -- Document the deletion for audit and compliance purposes -- Consider exporting server configuration before deletion for recovery - -## Warning - -This operation cannot be undone. To restore a deleted server, you must re-register it and re-synchronize all tools. Any tool-specific configurations or customizations will be lost. \ No newline at end of file diff --git a/www/docs/api-reference/agent-apis/tool-server/get-tool-server.md b/www/docs/api-reference/agent-apis/tool-server/get-tool-server.md index 04a1d6285..cbf2da825 100644 --- a/www/docs/api-reference/agent-apis/tool-server/get-tool-server.md +++ b/www/docs/api-reference/agent-apis/tool-server/get-tool-server.md @@ -6,17 +6,26 @@ sidebar_label: Get Tool Server import CodePanel from '@site/src/theme/CodePanel'; -The Get Tool Server API enables you to retrieve detailed information about a specific Model Context Protocol (MCP) server registered in your Vectara account. This API provides complete visibility into server configuration, connection details, and metadata, supporting troubleshooting, monitoring, and configuration management workflows. +The Get Tool Server API enables you to retrieve detailed information +about a specific Model Context Protocol (MCP) server registered in your +Vectara account. This API provides complete visibility into server +configuration, connection details, and metadata, supporting troubleshooting, +monitoring, and configuration management workflows. -Development teams use this API to verify server configurations, debug connectivity issues, audit security settings, and retrieve server details for documentation or integration planning. +Development teams use this API to verify server configurations, debug +connectivity issues, audit security settings, and retrieve server details +for documentation or integration planning. ## Get Tool Server Request and Response -To get tool server details, send a GET request to `/v2/tool_servers/{tool_server_id}`. You specify the following parameter: +To get tool server details, send a GET request to `/v2/tool_servers/{tool_server_id}`. +You specify the following parameter: -- `tool_server_id` (string, required): Tool server identifier in the URL path following pattern `tsr_[0-9a-zA-Z_-]+$` +- `tool_server_id` (string, required): Tool server identifier in the URL path + following pattern `tsr_[0-9a-zA-Z_-]+$` -The response includes the complete tool server configuration including connection details, metadata, and timestamps. +The response includes the complete tool server configuration including +connection details, metadata, and timestamps. ### Example Request @@ -73,10 +82,3 @@ The API returns standard HTTP error codes with detailed error information: | 403 | `forbidden` | Insufficient permissions for accessing this tool server | | 404 | `server_not_found` | Tool server with the specified ID does not exist | | 429 | `rate_limit_exceeded` | Request rate limit exceeded | - -## Usage Notes - -- Authentication details are not returned in the response for security reasons -- Use the metadata field to track custom information about the server -- The response can be used to verify server configuration before synchronization -- Consider caching server details locally to reduce API calls \ No newline at end of file diff --git a/www/docs/api-reference/agent-apis/tool-server/list-tool-servers.md b/www/docs/api-reference/agent-apis/tool-server/list-tool-servers.md index 14f5be1c4..d79cf24d5 100644 --- a/www/docs/api-reference/agent-apis/tool-server/list-tool-servers.md +++ b/www/docs/api-reference/agent-apis/tool-server/list-tool-servers.md @@ -6,21 +6,32 @@ sidebar_label: List Tool Servers import CodePanel from '@site/src/theme/CodePanel'; -The List Tool Servers API enables you to retrieve and browse all registered Model Context Protocol (MCP) servers in your Vectara account. This API provides visibility into the complete ecosystem of tool servers that expose enterprise capabilities to AI agents, facilitating server management, monitoring, and troubleshooting. +The List Tool Servers API enables you to retrieve and browse all +registered Model Context Protocol (MCP) servers in your Vectara account. +This API provides visibility into the complete ecosystem of tool servers +that expose enterprise capabilities to AI agents, facilitating server +management, monitoring, and troubleshooting. -Administrators and developers use this API to audit registered integrations, monitor server health and status, plan tool availability for agent configurations, and maintain an inventory of connected enterprise systems. +Use this API to audit registered integrations, monitor server health and +status, plan tool availability for agent configurations, and maintain an +inventory of connected enterprise systems. ## List Tool Servers Request and Response -To list tool servers, send a GET request to `/v2/tool_servers`. You can optionally specify the following query parameters: +To list tool servers, send a GET request to `/v2/tool_servers`. +You can optionally specify the following query parameters: -- `filter` (string, optional): A regular expression against tool server names and descriptions to filter results -- `type` (string, optional): Filter by server type (allowed value: `mcp`) -- `enabled` (boolean, optional): Filter servers by enabled status -- `limit` (integer, optional): Maximum number of servers to return per page (1-100, defaults to 10) -- `page_key` (string, optional): Pagination token from previous response to retrieve next page +- `filter` (string, optional): A regular expression against tool server + names and descriptions to filter results. +- `type` (string, optional): Filter by server type (allowed value: `mcp`). +- `enabled` (boolean, optional): Filter servers by enabled status. +- `limit` (integer, optional): Maximum number of servers to return per page + (1-100, defaults to 10). +- `page_key` (string, optional): Pagination token from previous response to + retrieve next page. -The response includes an array of tool server configurations with complete metadata and pagination information. +The response includes an array of tool server configurations with complete +metadata and pagination information. ### Example Request diff --git a/www/docs/api-reference/agent-apis/tool-server/sync-tool-server.md b/www/docs/api-reference/agent-apis/tool-server/sync-tool-server.md index efd362e3b..6273276a3 100644 --- a/www/docs/api-reference/agent-apis/tool-server/sync-tool-server.md +++ b/www/docs/api-reference/agent-apis/tool-server/sync-tool-server.md @@ -6,17 +6,23 @@ sidebar_label: Sync Tool Server import CodePanel from '@site/src/theme/CodePanel'; -The Sync Tool Server API enables you to trigger synchronization of a registered MCP server to discover and update its available tools. This API ensures that the Vectara platform maintains an accurate, up-to-date catalog of tools exposed by each server, automatically reflecting any changes in tool availability, schemas, or metadata. +The Sync Tool Server API enables you to synchronize a registered MCP server to +discover and update its available tools. T -Synchronization is essential after server deployment changes, tool additions or modifications, server configuration updates, or as part of regular maintenance to ensure tool discovery remains current. +Synchronization is essential after server deployment changes, tool additions or +modifications, server configuration updates, or as part of regular maintenance +to ensure tool discovery remains current. ## Sync Tool Server Request and Response -To synchronize a tool server, send a POST request to `/v2/tool_servers/{tool_server_id}/sync`. You specify the following parameter: +To synchronize a tool server, send a POST request to +`/v2/tool_servers/{tool_server_id}/sync`. You specify the following parameter: -- `tool_server_id` (string, required): Tool server identifier in the URL path following pattern `tsr_[0-9a-zA-Z_-]+$` +- `tool_server_id` (string, required): Tool server identifier in the URL path + following pattern `tsr_[0-9a-zA-Z_-]+$` -The request body should be empty. The API returns a 204 No Content response on successful synchronization. +The request body should be empty. The API returns a 204 No Content response +on successful synchronization. ### Example Request @@ -42,17 +48,6 @@ The request body should be empty. The API returns a 204 No Content response on s layout="stacked" /> -## Synchronization Process - -When you trigger a sync: - -1. The platform connects to the tool server using configured authentication -2. Discovers all available tools through the MCP protocol -3. Updates tool definitions, schemas, and metadata in the platform -4. Marks newly discovered tools as available for agent configuration -5. Preserves any tool-specific settings (like enabled/disabled status) -6. Deletes tools that no longer exist on the server - ## Error Responses The API returns standard HTTP error codes with detailed error information: @@ -66,10 +61,3 @@ The API returns standard HTTP error codes with detailed error information: | 409 | `sync_in_progress` | Another sync operation is already in progress | | 429 | `rate_limit_exceeded` | Sync rate limit exceeded | | 503 | `server_unavailable` | Tool server is not responding or is unavailable | - -## Notes - -- Synchronization is typically fast but may take longer for servers exposing many tools -- Tools are never deleted during sync; removed tools are marked as unavailable -- Sync operations are atomic - either all tools are updated or none are -- Consider scheduling regular syncs to maintain tool catalog accuracy \ No newline at end of file diff --git a/www/docs/api-reference/agent-apis/tool-server/update-tool-server.md b/www/docs/api-reference/agent-apis/tool-server/update-tool-server.md index 175ec84dd..966c6276b 100644 --- a/www/docs/api-reference/agent-apis/tool-server/update-tool-server.md +++ b/www/docs/api-reference/agent-apis/tool-server/update-tool-server.md @@ -6,24 +6,33 @@ sidebar_label: Update Tool Server import CodePanel from '@site/src/theme/CodePanel'; -The Update Tool Server API enables you to modify the configuration of registered Model Context Protocol (MCP) servers. This API supports updating connection parameters, authentication settings, metadata, and operational status, allowing you to maintain and evolve your tool server integrations without re-registration. +The Update Tool Server API enables you to modify the configuration of +registered Model Context Protocol (MCP) servers. This API supports +updating connection parameters, authentication settings, metadata, and +operational status, allowing you to maintain and evolve your tool server +integrations without re-registration. -Organizations use this API to update server endpoints after infrastructure changes, rotate authentication credentials, enable or disable servers for maintenance, update metadata for tracking and governance, and modify connection headers or parameters. +Use this API to update server endpoints after infrastructure changes, rotate +authentication credentials, enable or disable servers for maintenance, +update metadata for tracking and governance, and modify connection headers +or parameters. ## Update Tool Server Request and Response -To update a tool server, send a PATCH request to `/v2/tool_servers/{tool_server_id}`. You specify the following parameters: +To update a tool server, send a PATCH request to `/v2/tool_servers/{tool_server_id}`. +You specify the following parameters: -- `tool_server_id` (string, required): Tool server identifier in the URL path following pattern `tsr_[0-9a-zA-Z_-]+$` +- `tool_server_id` (string, required): Tool server identifier in the URL path + following pattern `tsr_[0-9a-zA-Z_-]+$`. - Request body parameters (all optional): - - `name` (string): The human-readable name of the tool server - - `description` (string): Updated description of server capabilities - - `uri` (string): The URI of the tool server - - `headers` (object): HTTP headers to include when connecting - - `transport` (string): Transport protocol (must be `sse` if provided) - - `auth` (object): Updated authentication configuration - - `enabled` (boolean): Whether the server should be enabled - - `metadata` (object): Updated arbitrary metadata + - `name` (string): The human-readable name of the tool server. + - `description` (string): Updated description of server capabilities. + - `uri` (string): The URI of the tool server. + - `headers` (object): HTTP headers to include when connecting. + - `transport` (string): Transport protocol (must be `sse` if provided). + - `auth` (object): Updated authentication configuration. + - `enabled` (boolean): Whether the server should be enabled. + - `metadata` (object): Updated arbitrary metadata. The response includes the complete updated tool server configuration. @@ -106,9 +115,3 @@ The API returns standard HTTP error codes with detailed error information: | 409 | `uri_conflict` | Another server already uses the specified URI | | 429 | `rate_limit_exceeded` | Update rate limit exceeded | -## Important Notes - -- Changes to URI or authentication may require re-synchronization -- Disabling a server makes all its tools unavailable to agents -- Consider testing connection changes before updating production servers -- Authentication credentials in responses are always redacted for security \ No newline at end of file diff --git a/www/docs/api-reference/agent-apis/tool/delete-tool.md b/www/docs/api-reference/agent-apis/tool/delete-tool.md index d98a0570f..f0e5adf99 100644 --- a/www/docs/api-reference/agent-apis/tool/delete-tool.md +++ b/www/docs/api-reference/agent-apis/tool/delete-tool.md @@ -4,19 +4,22 @@ title: Delete Tool API Definition sidebar_label: Delete Tool --- -# Delete Tool API Definition +The Delete Tool API enables you to remove a specific tool and its associated +configuration. This cannot be undone. -The Delete Tool API enables you to remove a specific tool from the Vectara platform's tool catalog, supporting tool lifecycle management and cleanup while enforcing safety constraints to prevent deletion of tools currently referenced by active agents. This API ensures that tool removal does not disrupt ongoing agent operations that depend on specific enterprise integrations. - -Organizations use this API for removing deprecated or obsolete tools from the catalog, cleaning up development and testing tools that are no longer needed, maintaining organized tool libraries as business requirements evolve, and ensuring proper governance of tool resources while protecting active agent deployments from accidental capability loss. +Use this API for removing deprecated or obsolete tools from the catalog ## Delete Tool Request and Response -To delete a tool, send a DELETE request to `/v2/tools/{tool_id}`. You specify the following parameter in the URL path: +To delete a tool, send a DELETE request to `/v2/tools/{tool_id}`. You specify +the following parameter in the URL path: -- `tool_id` (string, required): Unique tool identifier following the pattern `tool_[a-zA-Z0-9_-]+$` +- `tool_id` (string, required): Unique tool identifier following the pattern + `tool_[a-zA-Z0-9_-]+$` -The response returns HTTP status 204 (No Content) on successful deletion with no response body, indicating that the tool has been permanently removed from the platform catalog and is no longer available for agent configuration or usage. +The response returns HTTP status 204 (No Content) on successful deletion with +no response body, indicating that the tool has been permanently removed from +the platform catalog and is no longer available for agent configuration or usage. ### Example Request diff --git a/www/docs/api-reference/agent-apis/tool/get-tool.md b/www/docs/api-reference/agent-apis/tool/get-tool.md index ab5e48d17..e5bdd1fab 100644 --- a/www/docs/api-reference/agent-apis/tool/get-tool.md +++ b/www/docs/api-reference/agent-apis/tool/get-tool.md @@ -3,20 +3,22 @@ id: get-tool title: Get Tool API Definition sidebar_label: Get Tool --- +The Get Tool API enables you to retrieve the complete definition and +configuration details of a specific tool. -# Get Tool API Definition - -The Get Tool API enables you to retrieve the complete definition and configuration details of a specific tool discovered from Model Context Protocol (MCP) compliant tool servers, providing detailed visibility into tool capabilities, input schemas, and operational metadata for development and debugging purposes. This API supports detailed inspection of individual enterprise integration capabilities. - -Development teams and administrators use this API to inspect tool definitions during agent development, analyze tool input schemas and parameter requirements, review tool capabilities for agent configuration decisions, and maintain detailed understanding of specific enterprise system integrations that provide AI agent functionality. +Use this API to inspect tool definitions during agent development and review +tool capabilities for agent configuration decisions. ## Get Tool Request and Response -To retrieve a tool, send a GET request to `/v2/tools/{tool_id}`. You specify the following parameter in the URL path: +To retrieve a tool, send a GET request to `/v2/tools/{tool_id}`. You specify +the following parameter in the URL path: -- `tol_id` (string, required): Unique tool identifier following the pattern `tool_[a-zA-Z0-9_-]+$` +- `tool_id` (string, required): Unique tool identifier following the +- pattern `tool_[a-zA-Z0-9_-]+$` -The response includes the complete tool definition with input schema specification, source tool server information, categorization metadata, and all associated properties as discovered during tool server synchronization. +The response includes the complete tool definition and all associated +properties as discovered during tool server synchronization. ### Example Request diff --git a/www/docs/api-reference/agent-apis/tool/list-tools.md b/www/docs/api-reference/agent-apis/tool/list-tools.md index 0f9c79ecd..d60d4b1f4 100644 --- a/www/docs/api-reference/agent-apis/tool/list-tools.md +++ b/www/docs/api-reference/agent-apis/tool/list-tools.md @@ -6,21 +6,28 @@ sidebar_label: List Tools import CodePanel from '@site/src/theme/CodePanel'; -The List Tools API enables you to retrieve and browse all available tools discovered from registered Model Context Protocol (MCP) compliant tool servers, providing comprehensive visibility into the complete catalog of enterprise capabilities accessible to AI agents. This API facilitates tool discovery, capability planning, and agent configuration by presenting the unified tool ecosystem. - -Development teams and administrators use this API to explore available enterprise integrations for agent configuration, audit tool availability across different business systems, support tool selection during agent development workflows, and maintain operational awareness of the complete capability landscape that powers their AI agent infrastructure. +The List Tools API enables you to browse all available tools in your account. +Use this API to explore and audit tool availability. ## List Tools Request and Response -To list tools, send a GET request to `/v2/tools`. You can optionally specify the following query parameters: +To list tools, send a GET request to `/v2/tools`. You can optionally +specify the following query parameters: -- `filter` (string, optional): A regular expression against tool names and descriptions to filter the results -- `type` (string, optional): Filter tools by type (allowed value: `mcp`) +- `filter` (string, optional): A regular expression against tool names + and descriptions to filter the results +- `type` (string, optional): Filter tools by type (allowed value: + `mcp`) - `enabled` (boolean, optional): Filter tools by enabled status -- `limit` (integer, optional): Maximum number of tools to return per page (1-100, defaults to 10) -- `page_key` (string, optional): Pagination token from previous response to retrieve next page of results +- `limit` (integer, optional): Maximum number of tools to return per + page (1-100, defaults to 10) +- `page_key` (string, optional): Pagination token from previous + response to retrieve next page of results -The response includes an array of tool definitions with complete metadata including source tool server information, capability descriptions, parameter schemas, and operational details along with pagination information for retrieving additional results. +The response includes an array of tool definitions with complete +metadata including source tool server information, capability +descriptions, parameter schemas, and operational details along with +pagination information for retrieving additional results. ### Example Request @@ -143,9 +150,42 @@ The response includes an array of tool definitions with complete metadata includ layout="stacked" /> +## Available tools + +Vectara Agents support the following tool types: + +### Built-in tools + +* `corpora_search`: Retrieves results from Vectara corpora using Retrieval + Augmented Generation (RAG). This tool provides summary and relevant search results using + the same default parameters as the [Query API](/docs/api-reference/search-apis/search). + For more details about configuring the `corpora_search` tool, see + [**Configure Agent Search Behavior**](/docs/agents/#configure-agent-search-behavior). + +* `web_search`: Searches the public web for current information. Powered by Tavily, + this tool enables agents to access real-time data and recent developments that may not + be in your indexed corpora. + +### External and custom tools + +* `mcp`: Connect to external services through the Model Context Protocol (MCP). + MCP tools enable agents to integrate with external systems and services. See + [**Model Context Protocol**](/docs/agents/model-context-protocol) for details. + +* `lambda`: Execute custom Python functions in a secure, sandboxed environment. + Lambda tools allow you to define user-defined functions that agents can call to + perform custom logic, calculations, or data transformations. Currently supports + Python 3.12 with a curated set of libraries including numpy and pandas. + +* `structured_indexing`: Index structured documents into Vectara corpora with full + control over document structure, sections, metadata, tables, and images. This tool + enables agents to dynamically add content to your knowledge base during conversations. + + ## Error Responses -The API returns standard HTTP error codes with detailed error information: +The API returns standard HTTP error codes with detailed error +information: | HTTP Code | Error Code | Description | |-----------|------------|-------------| diff --git a/www/docs/api-reference/agent-apis/tool/update-tool.md b/www/docs/api-reference/agent-apis/tool/update-tool.md index c9a1ec21a..2d1b01072 100644 --- a/www/docs/api-reference/agent-apis/tool/update-tool.md +++ b/www/docs/api-reference/agent-apis/tool/update-tool.md @@ -6,20 +6,25 @@ sidebar_label: Update Tool import CodePanel from '@site/src/theme/CodePanel'; -The Update Tool API enables you to modify the configuration of existing tools discovered from MCP servers. Currently, this API supports enabling or disabling tools, allowing administrators to control tool availability for agent configurations without requiring changes to the underlying MCP server. +The Update Tool API enables you to modify the configuration of existing tools. -This API is essential for managing tool lifecycle, implementing phased rollouts of new capabilities, temporarily disabling problematic tools, and controlling which tools are available in different environments or for different user segments. +This API is essential for managing tool lifecycle, implementing phased rollouts +of new capabilities, temporarily disabling problematic tools, and controlling +which tools are available in different environments or for different user segments. ## Update Tool Request and Response -To update a tool, send a PATCH request to `/v2/tools/{tool_id}`. You specify the following parameters: +To update a tool, send a PATCH request to `/v2/tools/{tool_id}`. +You specify the following parameters: -- `tool_id` (string, required): Tool identifier in the URL path following pattern `tol_[0-9a-zA-Z_-]+$` +- `tool_id` (string, required): Tool identifier in the URL path following pattern + `tol_[0-9a-zA-Z_-]+$` - Request body parameters: - `type` (string, required): Must be `mcp` (only MCP tools can be updated) - `enabled` (boolean, required): Whether the tool should be enabled or disabled -The response includes the complete updated tool configuration with all metadata. +The response includes the complete updated tool configuration with all +metadata. ### Example Request diff --git a/www/docs/api-reference/search-apis/query-configuration.md b/www/docs/api-reference/search-apis/query-configuration.md new file mode 100644 index 000000000..fcd22aace --- /dev/null +++ b/www/docs/api-reference/search-apis/query-configuration.md @@ -0,0 +1,132 @@ +--- +id: query-configuration +title: Configure Query Parameters +sidebar_label: Configure Query Parameters +--- + +import CodePanel from '@site/src/theme/CodePanel'; + +Configuring your query parameters enables you to get the most relevant and +accurate results. This section covers the key configuration parameters that +control search behavior, result retrieval, reranking, context handling, and +AI-generated responses. + +## Corpora search configuration + +The `search` object controls which corpora to search and how to filter and +retrieve results: + +- **corpus_key** (required): Unique identifier for the corpus to search. +- **metadata_filter**: SQL-like filter to narrow results (`doc.year = '2024'`). +- **lexical_interpolation**: Balance between semantic (`0.0`) and keyword + (`1.0`) search. **Default:** `0.025`. +- **limit**: Maximum results to retrieve before reranking. **Default:** `10`. +- **offset**: Number of results to skip for pagination. +- **semantics**: Query interpretation mode ("`query`", "`response`", or + "`default`"). + + + +## Context configuration + +The `context_configuration` object controls how much surrounding text is +included with each search result: + +- **sentences_before/sentences_after**: Number of sentences to include + before/after matching text. +- **characters_before/characters_after**: Alternative character-based + boundaries for precise control. +- **start_tag/end_tag**: HTML tags for highlighting matching text in + results. + +:::note +You can only use **sentences before/after** or **characters before/after**, but not both. +::: + +", + "end_tag": "" + } + } +}`}]} title="Context Configuration Example" layout="stacked" /> + +## Reranker configuration + +[Rerankers](/docs/api-reference/search-apis/reranking) improve result quality by reordering search results to place the +most relevant content first: + +- **type**: Reranker type + - `customer_reranker`: Default multilingual reranker (recommended). + - `mmr`: Maximal Marginal Relevance to reduce redundancy. + - `none`: Disables reranking (not recommended). +- **reranker_name**: Specific reranker model (`Rerank_Multilingual_v1`). +- **limit**: Maximum results after reranking. +- **cutoff**: Minimum relevance score (`0.0-1.0`) for result inclusion. + Typically `0.3-0.7`. +- **include_context**: Use surrounding context text for more accurate + scoring. + + + +## Generation configuration + +The `generation` object controls how the agent creates natural language +responses: + +- **enabled**: Enable or disable generative summarization. +- **generation_preset_name**: Pre-configured prompt and model bundle (`mockingbird-2.0`). +- **max_used_search_results**: Number of top results to send to the LLM.. + **Default:** `5` +- **max_response_characters**: Soft limit for response length. +- **response_language**: Response language code (`auto`, `eng`, `spa`, etc.). +- **citations**: Citation formatting. + - **style**: Citation format (`numeric`, `html`, `markdown`, or `none`). + - **url_pattern**: URL template using metadata variables + (`https://docs.example.com/{doc.id}`). + - **text_pattern**: Display text template (`[{doc.title}]`). +- **prompt_template**: Override default prompt using Apache Velocity syntax. +- **model_parameters**: LLM settings (temperature, max_tokens, etc.). +- **enable_factual_consistency_score**: Validate factual consistency of + responses. + + diff --git a/www/docs/api-reference/search-apis/search.md b/www/docs/api-reference/search-apis/search.md index 1e88c4086..50faab0db 100644 --- a/www/docs/api-reference/search-apis/search.md +++ b/www/docs/api-reference/search-apis/search.md @@ -210,6 +210,70 @@ string. Usually, the default settings for the corpus are sufficient. In more advanced scenarios, it's desirable to force it to be treated as a query, or, more rarely, as a response. +### Search configuration + +The `search` object controls which corpora to search and how to filter and +retrieve results: + +- **corpus_key** (required): Unique identifier for the corpus to search. +- **metadata_filter**: SQL-like filter to narrow results (`doc.year = '2024'`). +- **lexical_interpolation**: Balance between semantic (`0.0`) and keyword + (`1.0`) search. **Default:** `0.025`. +- **limit**: Maximum results to retrieve before reranking. **Default:** `10`. +- **offset**: Number of results to skip for pagination. +- **semantics**: Query interpretation mode ("`query`", "`response`", or + "`default`"). + +### Context configuration + +The `context_configuration` object controls how much surrounding text is +included with each search result: + +- **sentences_before/sentences_after**: Number of sentences to include + before/after matching text. +- **characters_before/characters_after**: Alternative character-based + boundaries for precise control. +- **start_tag/end_tag**: HTML tags for highlighting matching text in + results. + +### Reranker configuration + +Rerankers improve result quality by reordering search results to place the +most relevant content first: + +- **type**: Reranker type + - `customer_reranker`: Default multilingual reranker (recommended). + - `mmr`: Maximal Marginal Relevance to reduce redundancy. + - `none`: Disables reranking (not recommended). +- **reranker_name**: Specific reranker model (`Rerank_Multilingual_v1`). +- **limit**: Maximum results after reranking. +- **cutoff**: Minimum relevance score (`0.0-1.0`) for result inclusion. + Typically `0.3-0.7`. +- **include_context**: Use surrounding context text for more accurate + scoring. + +### Generation configuration + +The `generation` object controls how the agent creates natural language +responses: + +- **enabled**: Enable or disable generative summarization. +- **generation_preset_name**: Pre-configured prompt and model bundle (`mockingbird-2.0`). +- **max_used_search_results**: Number of top results to send to the LLM.. + **Default:** `5` +- **max_response_characters**: Soft limit for response length. +- **response_language**: Response language code (`auto`, `eng`, `spa`, etc.). +- **citations**: Citation formatting. + - **style**: Citation format (`numeric`, `html`, `markdown`, or `none`). + - **url_pattern**: URL template using metadata variables + (`https://docs.example.com/{doc.id}`). + - **text_pattern**: Display text template (`[{doc.title}]`). +- **prompt_template**: Override default prompt using Apache Velocity syntax. +- **model_parameters**: LLM settings (temperature, max_tokens, etc.). +- **enable_factual_consistency_score**: Validate factual consistency of + responses. + + ### Reranking Configuration The `reranker` object enables the reranking of query results, to further diff --git a/www/docs/console-ui/agents/create-an-agent.md b/www/docs/console-ui/agents/create-an-agent.md index 821ed4552..047d98a2a 100644 --- a/www/docs/console-ui/agents/create-an-agent.md +++ b/www/docs/console-ui/agents/create-an-agent.md @@ -8,7 +8,8 @@ This section provides a step-by-step procedure for creating a custom AI agent in the Vectara platform. Agents are configurable AI entities that can leverage models, instructions, and tools to handle queries intelligently. You can create agents with the Vectara Console or programmatically through the API. -The Console is ideal for quick setups, while the API suits automation or advanced integrations. +The Console is ideal for quick setups, while the API suits automation or advanced +integrations. ```mermaid flowchart LR @@ -34,6 +35,11 @@ flowchart LR * Familiarity with JSON for overrides and parameters. * Supported models ("gpt-4o", "claude-sonnet-4"). +:::tip Tip +This example only uses the web_search tool. For details about configuring +the `corpora_search` tool, see [**Configure Agent Search Behavior**](/docs/agents/#configure-agent-search-behavior). +::: + The agent creation process follows a linear flow in the UI: 1. Access the **Agents** page from the sidebar. diff --git a/www/docs/learn/ai-agents.md b/www/docs/learn/ai-agents.md new file mode 100644 index 000000000..59aa5eb89 --- /dev/null +++ b/www/docs/learn/ai-agents.md @@ -0,0 +1,88 @@ +--- +id: ai-agents +title: AI Agents +sidebar_label: AI Agents +--- + +AI agents are autonomous systems that understand natural language, reason +through problems, use tools to accomplish tasks, and maintain context across +conversations. Unlike traditional chatbots that follow scripted responses, +agents can make decisions, access multiple data sources, and take actions to +achieve user goals. + +## What are AI agents? + +AI agents are systems or programs that automatically take actions to +accomplish specific goals. Modern agents powered by large language models +(LLMs) can understand natural language, reason through complex problems, and +interact with data and systems through instructions and tools. + +**Core capabilities:** + +- **Understand context**: Maintain conversation history and remember previous + interactions to provide coherent, context-aware responses. +- **Reason and plan**: Break down complex requests into steps, make + decisions about which tools to use, and adapt plans based on results. +- **Use tools**: Access databases, search the web, call APIs, run + calculations, and integrate with external systems to accomplish tasks. +- **Follow instructions**: Execute workflows based on customizable + instructions (also called system prompts) that define behavior and + objectives. +- **Stream responses**: Provide real-time updates as they process requests + and gather information. + +## What agents can accomplish + +| **Desired outcome** | **Workflow** | +|---|---| +| **Automate customer support workflows** |
  1. Agent handles L1 support
  2. Searches knowledge bases
  3. Escalates complex issues
  4. Creates tickets
| +| **Build intelligent research assistants** |
  1. Agent searches multiple data sources
  2. Synthesizes findings
  3. Maintains research context across sessions
| +| **Create workflow automation systems** |
  1. Agent triggers business processes
  2. Sends notifications
  3. Updates CRM systems based on natural language requests
| +| **Develop conversational enterprise tools** |
  1. Agent maintains context
  2. Handles multi-step processes
  3. Integrates with existing business systems
| +| **Deploy autonomous business processes** |
  1. Agent monitors conditions
  2. Makes decisions
  3. Executes actions without human intervention
| + +## How AI agents work + +AI agents typically follow a cycle of receiving input, reasoning about the +best approach, planning actions, and executing tasks using available tools. +This allows them to break down complex requests into manageable steps and +handle scenarios that require multiple data sources or actions. + +1. **Receive**: Receive and interpret user input or environmental changes. +2. **Reason**: Understand the goal and determine what information or actions + are needed. +3. **Plan**: Create a sequence of steps to accomplish the goal. +4. **Execute**: Use tools to gather information, perform calculations, or + take actions. +5. **Respond**: Synthesize results into a natural language response + +This cycle can repeat multiple times in a single conversation as the agent +gathers more information, refines its understanding, and works toward the +user's goal. + +## Building agents with Vectara + +Vectara provides a production-ready platform for building AI agents that +combine the power of RAG (Retrieval Augmented Generation) with tool calling, +session management, and enterprise-grade security. + +**Why Vectara for agents:** + +- **RAG-powered**: Agents can search your private corpora to ground responses + in your data, reducing hallucinations and ensuring accuracy. +- **Built-in tools**: Corpus search, web search, custom Python functions, and + external integrations through Model Context Protocol (MCP). +- **Session management**: Automatic conversation history, metadata for + personalization, and multi-turn context handling. +- **Dynamic behavior**: Use templates to customize instructions and tool + behavior based on user roles, permissions, or preferences. +- **Enterprise security**: Row-level access control, tenant isolation, and + auditable tool permissions. + +[**Build your first Vectara Agent β†’**](/docs/agents/agent-platform-overview) + +:::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) +::: diff --git a/www/docs/welcome.mdx b/www/docs/welcome.mdx index 865976563..ee9e53a85 100644 --- a/www/docs/welcome.mdx +++ b/www/docs/welcome.mdx @@ -10,14 +10,13 @@ import { Spacer } from "@site/src/components/ui/Spacer"; import { TopicButton } from "@site/src/components/ui/TopicButton"; import CodePanel from '@site/src/theme/CodePanel'; -Vectara is the trusted AI Agent platform that enables -enterprises to quickly deploy AI agents across the business grounded in their own data. -Retrieval Augmented Generation (RAG) at the core minimizes -hallucinations, supports 100+ languages, and delivers enterprise-grade -security for production-ready AI solutions. - -Deploy in your preferred environment, while maintaining complete data control. -User data remains secure because Vectara never trains on customer data. +Vectara is the Agent Operating System for trusted enterprise AI: a unified +Agentic RAG platform with built-in multi-modal retrieval, orchestration, and +always-on governance. Deploy it on-prem (air-gapped), in your VPC, or as SaaS. +Vectara agents deliver grounded answers and safe actions with source +citations, step-level audit trails, fine-grained access controls, and +real-time policy and factual-consistency enforcement, so teams ship faster +with lower risk, and with trusted, production-grade AI agents at scale.