update(docs): Enhance details about configuring agent search behavior #516
Conversation
✅ Deploy Preview for luxury-shortbread-acee05 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull Request Overview
This PR enhances documentation for configuring agent search behavior by adding comprehensive details about query configuration parameters and clarifying the relationship to the Query API. The changes make it clearer how to configure the corpora_search tool with the same parameters available in the Query API.
- Added a new "Configure agent search behavior" section with detailed examples and parameter explanations
- Added tip callouts referencing the new configuration section across multiple documentation files
- Corrected a tool type reference from "corpus_search" to "corpora_search"
Reviewed Changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| www/docs/console-ui/agents/create-an-agent.md | Added tip callout directing users to agent search behavior configuration documentation |
| www/docs/agents/tools.md | Enhanced corpora_search description with Query API reference and added link to configuration details |
| www/docs/agents/agents.md | Added comprehensive "Configure agent search behavior" section with detailed examples and parameter documentation |
| www/docs/agents/agents-quickstart.md | Added tip callout referencing search behavior configuration documentation |
| www/docs/agents/agent-platform-overview.md | Enhanced corpora search description with reference to configuration documentation |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
www/docs/agents/agents.md
Outdated
| }, | ||
| "reranker": { | ||
| "type": "customer_reranker", | ||
| "reranker_name": "Rerank_Multilingual_v1", |
There was a problem hiding this comment.
There's a trailing comma after the reranker_name value which will cause JSON parsing errors.
| "reranker_name": "Rerank_Multilingual_v1", | |
| "reranker_name": "Rerank_Multilingual_v1" |
www/docs/agents/agents.md
Outdated
| * Optional tool configurations, for example Corpora Search tools configured | ||
| to grant access to various corpora | ||
| :::tip Note | ||
| When using the corpora search tool |
There was a problem hiding this comment.
The tip note appears incomplete - it starts to mention something about the corpora search tool but doesn't provide any actual information or guidance.
| When using the corpora search tool | |
| When using the corpora search tool, ensure that your agent's `query_configuration` is set up correctly. This allows you to specify search parameters such as which corpora to query, filters, and ranking options. For more details, see the [Query API documentation](/docs/api-reference/search-apis/search) and the [corpora_search tool reference](/docs/agents/tools/corpora-search). |
www/docs/agents/agents.md
Outdated
| * Optional tool configurations, for example Corpora Search tools configured | ||
| to grant access to various corpora | ||
| :::tip Note | ||
| When using the corpora search tool |
There was a problem hiding this comment.
Incomplete sentence?
www/docs/agents/agents.md
Outdated
| API. For more information, check out our [**Agents Quick Start**](/docs/agents/agents-quickstart). | ||
| ::: | ||
|
|
||
| ## Configure agent search behavior |
There was a problem hiding this comment.
Since we have web search too, perhaps make it clear by saying "corpus search" instead of just "search".
www/docs/agents/agents.md
Outdated
|
|
||
| ## Configure agent search behavior | ||
|
|
||
| You configure search behavior for Vectara agents using the |
www/docs/agents/agents.md
Outdated
|
|
||
| You configure search behavior for Vectara agents using the | ||
| `query_configuration` parameter within the `corpora_search` tool. This | ||
| parameter uses the same `search` object formatting as the [Query API](/docs/api-reference/search-apis/search). Before |
There was a problem hiding this comment.
Is this really accurate? Isn't this both the search object, and generation?
Also, perhaps also add reference to the api doc page where this objects are? https://docs.vectara.com/docs/rest-api/query-corpus
wdyt?
www/docs/agents/agents.md
Outdated
| layout="stacked" | ||
| /> | ||
|
|
||
| ### Search configuration |
There was a problem hiding this comment.
Should we really repeat this configuration here or just reference the docs? By referring, if a new parameter is added, it'll automatically get reflected.
www/docs/agents/agents.md
Outdated
| parameter uses the same `search` object formatting as the [Query API](/docs/api-reference/search-apis/search). 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. |
There was a problem hiding this comment.
Where do we document the additional_parameters arg?
|
@nikron This PR started as updates to clarify agent search behavior. I decided to also incorporate some of the items from yesterday's meeting like moving the agent 101 stuff, making instructions more prominent, architecture updates, session keys, etc. |
| lets you customize instructions based on who is talking to the agent. | ||
| - **Tools use dynamic references**: Tools can use `argument_override` to | ||
| dynamically reference session metadata. This allows tools to filter data or | ||
| customize behavior based on the current user or context. |
There was a problem hiding this comment.
Giving the agent a restricted tool fit for purpose.
|
|
||
| Both agents and sessions use unique keys for identification: | ||
|
|
||
| - **Agent keys** (pattern: `agt_*`): You can specify a custom key like |
There was a problem hiding this comment.
agent keys don't require the agt_ prefix
| applications that go beyond basic question answering. Agents interpret user | ||
| input, reason through context, leverage external tools, and maintain continuity | ||
| across multi-turn interactions. | ||
| [AI agents](/docs/learn/ai-agents) are autonomous systems or programs that understand natural language |
There was a problem hiding this comment.
I don't think we need this link, since it just goes to the next page in the section. I clicked it, thinking it would bring me to some other resource to provide new context, but when it took me to the next page it felt a little silly. 😄
Also, I think this paragraph can be simplified to:
Agents are autonomous systems that understand natural language and use tools and reasoning to accomplish tasks.
| [**Learn more about Sessions →**](/docs/agents/sessions) | ||
|
|
||
|
|
||
| ## Getting Started |
There was a problem hiding this comment.
I suggest elevating this section to immediately follow the initial introductory sentence. Engineers learn by doing.
There was a problem hiding this comment.
Also, the order is incorrect. Writing instructions should go before tools.
| Corpus["Corpus Search"] | ||
| Web["Web Search"] | ||
| %% Tools layer | ||
| AvailableTools["**Tools** (Corpora Search, Web Search, Lamba Tools)"] |
There was a problem hiding this comment.
Typo: "Lamba" -> "Lambda"
| - Define the agent's persona and objectives. | ||
| - Customize responses based on context. | ||
| - Support dynamic variable substitution. | ||
| Vectara agents follow a structured flow where **instructions** define the |
There was a problem hiding this comment.
I think we should move this content under a "Concepts" heading, along with everything below up until "Getting started".
I think we should also adjust this wording so that it's clearer that we're just snapping our fingers here and saying, "Listen up this is important. If you are to take anything away from this, it's this bit here."
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 guide agent behavior**: Instructions define the agent's persona, |
There was a problem hiding this comment.
I think we should remove this section. It's largely redundant with the information from the Agents, Instructions, Tools, and Sessions sections below. It also introduces low-level details such as session metadata and tools' argument_override, which is better surfaced in the API docs, and discusses "templates" which are a detail of instructions and not a top-level concept on par with them (IMO).
|
|
||
| ## Agents | ||
|
|
||
| Agents act as the orchestration layer of the platform. They coordinate |
There was a problem hiding this comment.
This is confusing to me because we're defining them as both "autonomous systems" and "orchestration layers". I don't know how to make sense of that?
There's also a lot of low-level detail that will be more helpful in the REST API docs.
| agent's persona and objectives, customize responses based on context, and | ||
| support dynamic variable substitution from session metadata. | ||
|
|
||
| Instructions are the most important component to configure. Start here when |
There was a problem hiding this comment.
I think this statement is redundant with the intro and the Getting Started section.
| ## Tools | ||
|
|
||
| Tools provide agents with capabilities to interact with data and external | ||
| systems. Vectara provides the following built-in tools: |
There was a problem hiding this comment.
The list of tools is better in the REST API docs. It will also make maintenance better because there will be fewer places to update.
|
|
||
| [**Learn more about Tools →**](/docs/agents/tools) | ||
|
|
||
| ## Sessions |
There was a problem hiding this comment.
I think we should condense these four headings into bullets under a "Concepts" heading.
Concepts
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.
These are the other core concepts when it comes to agents:
- 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.
|
|
||
| ## Sessions | ||
|
|
||
| Sessions maintain the state of conversations. They track all interactions |
There was a problem hiding this comment.
Seems like there is a lot of redundant info here:
- state of conversation
- track all interactions within a conversation
- context across multiple turns
I think these are all the same thing?
There was a problem hiding this comment.
I have a few comments to clarify the diagram:
- I think "User/Application" should simply be "User", since there will also be a user of the application, so it all boils down to the user entering a query.
- The agent can respond with things other than answers, e.g. clarifying questions, tool outputs, images, and search results. I suggest changing "Answer" to "Response", to capture all the possibilities.
- "Agent" looks like a component of "Agent session" here which seems inverted. I chatted a bit with Pranav and he suggested swapping the two, which really helped me make sense of this entire diagram. Let's also just call it "Session", since we make it very clear in this page how they relate to agents.
- Unless we care to explain the difference between "Direct answer" and "Synthesize response" I think we should just remove "Direct answer". From the diagram, it's not clear what the difference is between the two.
- Agents use an MCP tool to access the MCP client, so I suggest renaming this bit to "MCP Tool + Client" to create symmetry with the other Tools.
- There are many colors and line treatments here, the meaning of which aren't clear. I suggest we use the same gray boxes for everything inside of Vectara (Agent, Session, Instructions, Tools, Agent Query, MCP Tool + Client), and the same black boxes for everything outside of Vectara (User, External MCP Server). I also suggest we avoid using the dashed lines, and just use the same line style for all of the arrows. The meaning of the different line styles aren't clear to me.
www/docs/agents/instructions.md
Outdated
| behavior, and guidelines of an agent before any user interaction begins. | ||
| ::: | ||
|
|
||
| You can configure instructions for an agent in two ways: **inline** or |
There was a problem hiding this comment.
I think the Inline Instructions and Shared (Reference) Instructions sections should be moved into the POST Create Instruction API docs because that's where the engineer will be looking when they need this info.
Also, the API docs need to be reordered, so that Instructions, Tools, and Tool Servers follow Agent Sessions.
There was a problem hiding this comment.
I'll initially make updates/moves to the long-form API docs (API Concepts chapter). Adding different headings and subsections to the yaml is more complex. It can be done, but separately on the platform repo. The reordering must also be done in the yaml in the tag section.
www/docs/agents/instructions.md
Outdated
| and providing the rules for the underlying Large Language Model (LLM). | ||
|
|
||
| Instructions use the [Apache Velocity](https://velocity.apache.org/) templating | ||
| Instructions define the behavior that agents follow. They are the most important |
There was a problem hiding this comment.
I suggest replacing this content with what we have in the overview. The repetition is useful because a) it helps folks connect the dots and b) if someone has already read it they know they can skip over it. Mentioning Velocity templating is out of place here IMO because it's too low-level. Better to save that for the section dedicated to the topic.
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.
www/docs/agents/instructions.md
Outdated
| engine, which enables you to dynamically insert variables into your prompts. | ||
|
|
||
|
|
||
| - **Define agent behavior**: Set the persona, objectives, response |
There was a problem hiding this comment.
These bullets confuse me... can we remove them? They're a lot of very specific detail, and yet there isn't enough information for me to make use of the detail. I end up kind of overloaded when I read it. For example, the ${session.metadata.field} and argument_override stuff doesn't mean anything to me without more explanation.
www/docs/agents/instructions.md
Outdated
| :::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 work the same way. Instructions define the role, |
There was a problem hiding this comment.
This tip is great, but instead of "work the same way", I think we should phrase it as "serve a similar purpose". Our instructions don't work the same way, e.g. our instructions can be used as templates.
www/docs/agents/instructions.md
Outdated
| layout="stacked" | ||
| /> | ||
|
|
||
| ## Template Context |
There was a problem hiding this comment.
I think we should change this heading to "Templating". "Templating" is a concept, whereas "Template context" is a technical term, and I think concept come across as more accessible to folks who may not be familiar with the technical details yet.
www/docs/agents/instructions.md
Outdated
|
|
||
| ### Tools context | ||
|
|
||
| - `$tools`: A list of tools available to the agent. You can iterate over tools to display their names and descriptions in your instructions. |
There was a problem hiding this comment.
This shouldn't be a bullet.
www/docs/agents/instructions.md
Outdated
| - `${agent.metadata.field}`: Access agent-level metadata (version, | ||
| configuration, environment). | ||
|
|
||
| ## Use metadata in instructions |
There was a problem hiding this comment.
I don't think this section or the "Session metadata examples" are useful. By describing "you can do X" without showing how to do it, it sounds like marketing. I suggest removing them.
There was a problem hiding this comment.
I think what we should really do is ask a PM or DevRel to choose 3 or 4 of the coolest items from these lists and then write up a blog post showing how to implement them step-by-step. CC @koala-woman @ofermend
| - `escalation_needed` (true/false): Track when to hand off to human. | ||
| - `channel` (web, mobile, API, voice): Adjust response format and length. | ||
|
|
||
| ### Metadata usage example |
There was a problem hiding this comment.
OTOH this example is very useful! I suggest taking the entire example and moving it into the "Metadata context" section. It doesn't need a new heading.
www/docs/agents/instructions.md
Outdated
| The instruction renders as: | ||
| > "Hello! I see you're John Doe from North America. I'm here to help you with billing inquiries." | ||
| ### Custom variables |
There was a problem hiding this comment.
I think this content belongs in the POST Test Instruction API docs.
www/docs/agents/instructions.md
Outdated
| render with different context values before deploying them in production agents. | ||
|
|
||
| :::note Important | ||
| For the current version, agent and session metadata are not directly included |
There was a problem hiding this comment.
This is very easy to overlook because it looks like a footnote. But it contains critical information for actually using the stuff described above.
However, I'm confused about what's described here. It mentions "instruction template scope" but then it mentions "tool excecution". Is this about instructions, tools, or both? @pranavh4 Can you clarify this?
There was a problem hiding this comment.
We are adding this to the instruction template scope very soon, I agree we should remove this note
| * An input schema describing accepted parameters (in JSON Schema format). | ||
| * Metadata for categorization. | ||
| * Runtime availability (enabled/disabled). | ||
| * Runtime availability (enabled or disabled). |
There was a problem hiding this comment.
I think we should focus long-form doc intros on the concept, and leave details to the REST API docs. I suggest removing these bullets and echoing the same language we used in the top-level intro.
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.
www/docs/agents/tools.md
Outdated
| * **web_search:** Retrieves results from the public web. | ||
| Vectara Agents support the following tool types: | ||
|
|
||
| ### Built-in tools |
There was a problem hiding this comment.
I think all of this information about specific tools should be moved to the List Tools API docs.
www/docs/agents/tools.md
Outdated
| control over document structure, sections, metadata, tables, and images. This tool | ||
| enables agents to dynamically add content to your knowledge base during conversations. | ||
|
|
||
| ## Tool permissions and security |
There was a problem hiding this comment.
I think we should remove this section, unless we can link out to a resource that provides more context.
www/docs/agents/tools.md
Outdated
| 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). |
There was a problem hiding this comment.
I think we should extract the "Configure agent corpus search behavior" section from the Agent page and move it into this page instead, since that section is a great example on how to configure tools for their most common use case (retrieval). I think "Searching corpora with tools" would be a more accessible heading.
| agent decides how to respond to user input, when to invoke tools, and how to | ||
| manage conversation state. | ||
|
|
||
| ```mermaid |
There was a problem hiding this comment.
I think "core orchestration unit" is a very internal way of looking at agents. I think we should avoid this language, to keep the docs accessible and developer-focused. We can still explain how things work internally, but we can make these explanations accessible by anchoring them to concepts.
I suggest rewriting the intro at the top of this page as:
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.
www/docs/agents/agents.md
Outdated
| ``` | ||
|
|
||
| Each agent is configured with: | ||
| :::tip Quick Start |
There was a problem hiding this comment.
I think this is an odd place to surface the link to the Quick Start. I think this will be more discoverable in the top-level Agents page.
www/docs/agents/agents.md
Outdated
| For a complete step-by-step guide with code examples, see [**Agent Quick Start**](/docs/agents/agents-quickstart). | ||
| ::: | ||
|
|
||
| ## Configure agents |
There was a problem hiding this comment.
I think all of the content under this heading belongs in the Create Agent API docs.
www/docs/agents/agents.md
Outdated
| treat `first_step` as "the step." It's the only step your agent executes. | ||
| ::: | ||
|
|
||
| Agents operate through a conversational step architecture, processing user |
There was a problem hiding this comment.
I think this paragraph is redundant though. I think we should remove it.
www/docs/agents/agents.md
Outdated
| API. For more information, check out our [**Agents Quick Start**](/docs/agents/agents-quickstart). | ||
| ::: | ||
|
|
||
| ## Configure agent corpus search behavior |
There was a problem hiding this comment.
As mentioned prior I think this should move to the Tools page.
www/docs/agents/agents.md
Outdated
| layout="stacked" | ||
| /> | ||
|
|
||
| This example demonstrates a complete `tool_configurations` object for a |
There was a problem hiding this comment.
I think we should remove this example. It kind of makes the point that the Corpora Search tool supports the same configuration options as the Query API, but it's a bit over the top IMO. The Query API docs have tons of examples already.
www/docs/agents/agents.md
Outdated
|
|
||
|
|
||
|
|
||
| ## Example agent definition |
There was a problem hiding this comment.
I think this belongs in the API docs.
www/docs/agents/agents.md
Outdated
| layout="stacked" | ||
| /> | ||
|
|
||
| ## Model configuration |
There was a problem hiding this comment.
"LLM" is more recognizable and meaningful, and I think we can also tie back to the role of the LLM within the agent, to make this heading clearer. So I suggest changing this heading to "Orchestrating behavior with the LLM".
www/docs/agents/agents.md
Outdated
| - **Cost optimization**: Balance performance with token usage. | ||
| - **Retry configuration**: Configure automatic retry behavior for transient failures. | ||
|
|
||
| ### Retry configuration |
There was a problem hiding this comment.
Can we make this section much terser? It seems strange to dedicate so much content to retries.
Can we also change the heading to "Using retries to improve user experience"?
Using retries to improve user experience
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.
Here's a brief explanation of how retries work:
- 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_factordoesn't create an unreasonably long delay for your users.
I'd delete the section under the "Exponential backoff" heading, too, because it goes way too deep into this topic.
www/docs/agents/agents.md
Outdated
| layout="stacked" | ||
| /> | ||
|
|
||
| ### 2. Send messages to the agent |
There was a problem hiding this comment.
I think we should move the entire "Chat with your agent" section into the "Sessions" page and we should end this page with "To chat with your agent, read on about Sessions".
www/docs/agents/sessions.md
Outdated
|
|
||
| import CodePanel from '@site/src/theme/CodePanel'; | ||
|
|
||
| A session is a contextual container for a conversation between a user (or |
There was a problem hiding this comment.
I think we can make this more accessible and much simpler by focusing on the concept. My suggestion:
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.
www/docs/agents/sessions.md
Outdated
| Sessions support lifecycle operations such as creation, update, retrieval, | ||
| listing, and deletion. | ||
|
|
||
| ## Session keys |
There was a problem hiding this comment.
Let's insert a section preceding this one called "Chatting with an agent". This section will contain the example from the end of the Agent page. That way folks will get an immediate example of the concepts just described in the intro, and it will also enable them with a mini "quick start".
www/docs/agents/sessions.md
Outdated
|
|
||
| ## Session keys | ||
|
|
||
| Every session has a unique `key` that identifies it in API calls. You have |
There was a problem hiding this comment.
I think the content under this heading belongs in the API docs.
When we move them there, I suggest we elaborate a bit and tie back to why the reader should care.
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 thekeywhen you create the session, Vectara will automatically generate one for you. If you prefer your session keys to convey meaning, you can define thekeyas part of the request.
www/docs/agents/sessions.md
Outdated
| Every session has a unique `key` that identifies it in API calls. You have | ||
| two options for session keys, **auto-generated** or **custom**: | ||
|
|
||
| ### Auto-generated keys |
There was a problem hiding this comment.
I don't think these code examples are necessary. The above explanation is sufficient for the reader to understand.
www/docs/agents/sessions.md
Outdated
| layout="stacked" | ||
| /> | ||
|
|
||
| **Common patterns:** |
There was a problem hiding this comment.
I think we can remove this. The reader is in a better position to decide what kinds of keys make the most sense.
www/docs/agents/sessions.md
Outdated
| - Support ticket: `ticket_{ticket_number}_session` | ||
|
|
||
|
|
||
| ## Session Metadata |
There was a problem hiding this comment.
How about "Define session context with session metadata" to bring it back to the use case?
|
|
||
| ## Session Metadata | ||
|
|
||
| Session metadata provides context-specific data to agents, enabling |
There was a problem hiding this comment.
Can we frame this in terms of the user a bit more? For example:
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.
Here's how you might implement the language preference and access control examples.
(Code snippet from below)
Then you'd write an instruction like this, to respond in the preferred language.
(New code snippet)
And you'd configure a corpora search tool like this, to limit the user's access to certain corpora.
(New code snippet)
www/docs/agents/sessions.md
Outdated
| "key": "user_12345_session", | ||
| "name": "Customer Support Session", | ||
| "metadata": { | ||
| "customer_id": "12345", |
There was a problem hiding this comment.
Let's limit this to just language and user_role, to support the preferred language and access control examples.
www/docs/agents/sessions.md
Outdated
| /> | ||
|
|
||
|
|
||
| ## Agent events |
There was a problem hiding this comment.
I think we can move the rest of the content from here, down, into the API docs.
There was a problem hiding this comment.
It's not part of this PR, but I reviewed the MCP section. I think we should remove the content under the "Why MCP is important" heading, to keep the docs focused on how MCP pertains to Vectara.
Let's also remove the entire "Conversational AI" section. I don't find it very helpful.
| 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 |
There was a problem hiding this comment.
I think we should edit this page down to minimize the time it takes to go from zero to agent.
Let's reduce the intro to:
Build a simple research assistant agent that can search the web in response to user queries. To learn more about agents, refer to the Agents API docs or read about agent concepts.
Then let's walk the user through creating the agent in Console, show the user the underlying API request for creating the agent, and then provide code snippets for creating a session and sending user message events to it with the API.
The "Response example", "Complete Example" (with curl), "Expected response", and "Response format" sections can be removed. I think they provide too much detail for a quick start.
| "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}.", |
There was a problem hiding this comment.
Docusaurus is trying to interpolate currentDate which causes this page to throw an error. You need to escape the $, {, and } characters like this:
\$\{currentDate\}
| ## What is an agent? | ||
|
|
||
| An agent is comprised of three main components of functionality: | ||
| An agent is an AI-powered orchestrator comprised of three main components: |
There was a problem hiding this comment.
I find it really confusing to have an entire parallel set of docs called "API concepts", while we also have long-form concept-focused docs and REST API docs. Much of the content is duplicated, which makes it harder for the reader to know where to look for the info they need. I think we should remove these and divvy up the content among the long-form docs and REST API docs.
| 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 |
There was a problem hiding this comment.
I don't think folks need a manual on how to use Console. We should remove most of these Console docs, and lean on a few quick starts to help users get momentum. For the most part the Console UI should be self-explanatory.
| @@ -0,0 +1,88 @@ | |||
| --- | |||
| id: ai-agents | |||
There was a problem hiding this comment.
We should delete this page. It repeats a lot of content that exists elsewhere and contains a lot of claims of capabilities but zero guidance on applying them.
www/docs/agents/instructions.md
Outdated
| other context you provide when creating a session. | ||
| - **Guide tool usage**: Tell the agent when and how to use specific tools, | ||
| what information to gather, and how to structure responses. | ||
| - **Work with argument overrides**: Instructions guide what the agent does, |
There was a problem hiding this comment.
I dont think argument_overrides should even be mentioned in instructions.md, since they're not related at all. They only apply to tool_configurations and are difficult to understand as it is
www/docs/agents/agents.md
Outdated
| use these references to access files without including the full content in | ||
| every request. | ||
|
|
||
| ## How artifacts work |
There was a problem hiding this comment.
This heading should be nested under "Artifacts".
www/docs/agents/agents.md
Outdated
|
|
||
| To chat with your agent, read on about [Sessions](/docs/agents/sessions). | ||
|
|
||
| ## Artifacts |
There was a problem hiding this comment.
Because artifacts are so pertinent to the session, I think this content should be moved to the Sessions page.
5 participants
Enhanced content around configuring agent search behavior. It's not always clear that it's similar to the Query API parameters.