Skip to main content
Version: 2.0

Agents Quick Start

Vectara Agents are AI assistants that can use tools, follow instructions, and maintain conversation context. This guide shows you how to create and interact with a Vectara agent using the API. We'll walk through the workflow from agent creation to having a conversation. Here is some information about using agents:

  • Sessions are required: You cannot chat with an agent directly. You must create a session first.
  • Sessions maintain context: All messages within a session share conversation history.
  • One agent, many sessions: Multiple users can have separate conversations with the same agent.
  • Event-based architecture: All interactions are tracked as events for full auditability.

The agent workflow follows these steps:

  1. Create an agent - Configure your AI assistant with tools and instructions.
  2. Create a session - Start a conversation context for message history.
  3. Send messages - Chat with the agent through the session.

Let's walk through each step with working examples.

Step 1: Create an Agent​

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.

For your first agent, we recommend using the Console UI. If you need more detailed UI instructions, see Create an Agent.

  1. Navigate to Agents in the sidebar.
  2. Click Add Agent.
  3. Configure each step:
    • General: Name: research-assistant and description: A research assistant that can search the web for current information
    • Model: Select gpt-5, and set {"temperature":0.3} for factual responses
    • Instructions: You are a helpful research assistant. When users ask questions, search the web for current and accurate information. Always cite your sources and be honest if you cannot find reliable information.
    • Tools: Add Web Search tool with the argument override: {"limit": 10}.
    • Advanced: Add {"category": "research"}.
  4. Click Create Agent.

Create an agent with the API​

Alternatively, create the same agent programmatically:

Curl Command Format

If you have issues with copy-pasting multi-line command, use a single-line version.

CREATE A RESEARCH ASSISTANT AGENT
1?

This creates an agent with an auto-generated key like agt_research-assistant_abc123.

RESPONSE EXAMPLE
1

Step 2: Create a Session​

First, create a session to maintain conversation context:

CREATE A SESSION
1

This returns a session object with a key ( ase_12345) that you need in the next step.

Step 3: Chat with the Agent​

Send user input by creating an event in the session:

CHAT WITH THE AGENT
1

Complete Example​

Here's a complete example using curl:

COMPLETE AGENT CHAT EXAMPLE
1?

Test your agent with the console UI​

  1. In the agent details page, click the Chat tab.
  2. Try asking: "What are the main benefits of solar energy for average Texas homes?"
  3. You should see the agent search the web and provide a cited response.

Expected response​

The agent acts as follows:

  1. Uses web search to find current information.
  2. Provides a summary with key points.
  3. Includes source citations.
  4. Shows tool usage in the response events.

Response format​

The agent responds with events that include:

  • input_message: Your original message
  • thinking: The agent's reasoning process (optional)
  • tool_input/tool_output: Web search execution and results
  • agent_output: The final response with citations.