vectara-agentic 0.2.12__py3-none-any.whl → 0.2.14__py3-none-any.whl

{vectara_agentic-0.2.12.dist-info → vectara_agentic-0.2.14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vectara_agentic
-Version: 0.2.12
+Version: 0.2.14
 Summary: A Python package for creating AI Assistants and AI Agents with Vectara
 Home-page: https://github.com/vectara/py-vectara-agentic
 Author: Ofer Mendelevitch
@@ -16,18 +16,18 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: llama-index==0.12.30
-Requires-Dist: llama-index-indices-managed-vectara==0.4.2
+Requires-Dist: llama-index==0.12.33
+Requires-Dist: llama-index-indices-managed-vectara==0.4.4
 Requires-Dist: llama-index-agent-llm-compiler==0.3.0
 Requires-Dist: llama-index-agent-lats==0.3.0
 Requires-Dist: llama-index-agent-openai==0.4.6
-Requires-Dist: llama-index-llms-openai==0.3.35
+Requires-Dist: llama-index-llms-openai==0.3.38
 Requires-Dist: llama-index-llms-anthropic==0.6.10
 Requires-Dist: llama-index-llms-together==0.3.1
 Requires-Dist: llama-index-llms-groq==0.3.1
 Requires-Dist: llama-index-llms-fireworks==0.3.2
 Requires-Dist: llama-index-llms-cohere==0.4.1
-Requires-Dist: llama-index-llms-gemini==0.4.14
+Requires-Dist: llama-index-llms-google-genai==0.1.8
 Requires-Dist: llama-index-llms-bedrock==0.3.8
 Requires-Dist: llama-index-tools-yahoo-finance==0.3.0
 Requires-Dist: llama-index-tools-arxiv==0.3.0
@@ -39,15 +39,17 @@ Requires-Dist: llama-index-tools-neo4j==0.3.0
 Requires-Dist: llama-index-graph-stores-kuzu==0.7.0
 Requires-Dist: llama-index-tools-slack==0.3.0
 Requires-Dist: llama-index-tools-exa==0.3.0
+Requires-Dist: llama-index-tools-wikipedia==0.3.0
+Requires-Dist: llama-index-tools-bing-search==0.3.0
 Requires-Dist: tavily-python==0.5.4
-Requires-Dist: exa-py==1.9.1
-Requires-Dist: openinference-instrumentation-llama-index==3.3.3
-Requires-Dist: opentelemetry-proto==1.31.0
-Requires-Dist: arize-phoenix==8.14.1
-Requires-Dist: arize-phoenix-otel==0.8.0
+Requires-Dist: exa-py==1.12.0
+Requires-Dist: openinference-instrumentation-llama-index==4.2.1
+Requires-Dist: opentelemetry-proto==1.32.1
+Requires-Dist: arize-phoenix==8.26.1
+Requires-Dist: arize-phoenix-otel==0.9.2
 Requires-Dist: protobuf==5.29.3
 Requires-Dist: tokenizers>=0.20
-Requires-Dist: pydantic==2.10.6
+Requires-Dist: pydantic==2.11.3
 Requires-Dist: retrying==1.3.4
 Requires-Dist: python-dotenv==1.0.1
 Requires-Dist: tiktoken==0.9.0
@@ -70,7 +72,7 @@ Dynamic: summary
 
 <p align="center">
   <a href="https://vectara.github.io/py-vectara-agentic">Documentation</a> ·
-  <a href="#examples">Examples</a> ·
+  <a href="#example-ai-assistants">Examples</a> ·
   <a href="https://discord.gg/S9dwgCNEFs">Discord</a>
 </p>
 
@@ -84,8 +86,24 @@ Dynamic: summary
   <a href="https://twitter.com/vectara">
     <img src="https://img.shields.io/twitter/follow/vectara.svg?style=social&label=Follow%20%40Vectara" alt="Twitter">
   </a>
+  <a href="https://pypi.org/project/vectara-agentic/">
+    <img src="https://img.shields.io/pypi/v/vectara-agentic.svg" alt="PyPI version">
+  </a>
+  <a href="https://pypi.org/project/vectara-agentic/">
+    <img src="https://img.shields.io/pypi/pyversions/vectara-agentic.svg" alt="Python versions">
+  </a>
 </p>
 
+## 📑 Table of Contents
+
+- [Overview](#-overview)
+- [Quick Start](#-quick-start)
+- [Using Tools](#using-tools)
+- [Advanced Usage: Workflows](#advanced-usage-workflows)
+- [Configuration](#️-configuration)
+- [Contributing](#-contributing)
+- [License](#-license)
+
 ## ✨ Overview
 
 `vectara-agentic` is a Python library for developing powerful AI assistants and agents using Vectara and Agentic-RAG. It leverages the LlamaIndex Agent framework and provides helper functions to quickly create tools that connect to Vectara corpora.
@@ -107,9 +125,9 @@ Dynamic: summary
 - **Observability:**  
   Built-in support with Arize Phoenix for monitoring and feedback.
 - **Workflow Support:**  
-  Extend your agent’s capabilities by defining custom workflows using the `run()` method.
+  Extend your agent's capabilities by defining custom workflows using the `run()` method.
 
-### 📚 Example AI Assistants
+### Example AI Assistants
 
 Check out our example AI assistants:
 
@@ -118,14 +136,14 @@ Check out our example AI assistants:
 - [Legal Assistant](https://huggingface.co/spaces/vectara/legal-agent)
 - [EV Assistant](https://huggingface.co/spaces/vectara/ev-assistant)
 
-###  Prerequisites
+### Prerequisites
 
 - [Vectara account](https://console.vectara.com/signup/?utm_source=github&utm_medium=code&utm_term=DevRel&utm_content=vectara-agentic&utm_campaign=github-code-DevRel-vectara-agentic)
 - A Vectara corpus with an [API key](https://docs.vectara.com/docs/api-keys)
 - [Python 3.10 or higher](https://www.python.org/downloads/)
 - OpenAI API key (or API keys for Anthropic, TOGETHER.AI, Fireworks AI, Bedrock, Cohere, GEMINI or GROQ, if you choose to use them)
 
-###  Installation
+### Installation
 
 ```bash
 pip install vectara-agentic
@@ -133,6 +151,8 @@ pip install vectara-agentic
 
 ## 🚀 Quick Start
 
+Let's see how we create a simple AI assistant to answer questions about financial data ingested into Vectara, using `vectara-agentic`. 
+
 ### 1. Initialize the Vectara tool factory
 
 ```python
@@ -147,7 +167,7 @@ vec_factory = VectaraToolFactory(
 
 ### 2. Create a Vectara RAG Tool
 
-A RAG tool calls the full Vectara RAG pipeline to provide summarized responses to queries grounded in data.
+A RAG tool calls the full Vectara RAG pipeline to provide summarized responses to queries grounded in data. We define two additional arguments (`year` and `ticker` that map to filter attributes in the Vectara corpus):
 
 ```python
 from pydantic import BaseModel, Field
@@ -164,48 +184,60 @@ class QueryFinancialReportsArgs(BaseModel):
     year: int | str = Field(..., description=f"The year this query relates to. An integer between {min(years)} and {max(years)} or a string specifying a condition on the year (example: '>2020').")
     ticker: str = Field(..., description=f"The company ticker. Must be a valid ticket symbol from the list {tickers.keys()}.")
 
-query_financial_reports_tool = vec_factory.create_rag_tool(
+ask_finance = vec_factory.create_rag_tool(
     tool_name="query_financial_reports",
     tool_description="Query financial reports for a company and year",
     tool_args_schema=QueryFinancialReportsArgs,
     lambda_val=0.005,
     summary_num_results=7, 
-    # Additional arguments
+    # Additional Vectara query arguments...
 )
 ```
 
-Note that we only defined the `year` and `ticker` arguments. The `query` argument is automatically added by `vectara-agentic`.
+> **Note:** We only defined the `year` and `ticker` arguments in the QueryFinancialReportsArgs model. The `query` argument is automatically added by `create_rag_tool`.
 
-See the [docs](https://vectara.github.io/py-vectara-agentic/latest/) for additional arguments to customize your Vectara RAG tool.
+To learn about additional arguments `create_rag_tool`, please see the full [docs](https://vectara.github.io/py-vectara-agentic/latest/).
 
 ### 3. Create other tools (optional)
 
-In addition to RAG tools, you can generate a lot of other types of tools the agent can use. These could be mathematical tools, tools 
+In addition to RAG tools or search tools, you can generate additional tools the agent can use. These could be mathematical tools, tools 
 that call other APIs to get more information, or any other type of tool.
 
-See [Agent Tools](#agent-tools) for more information.
+See [Agent Tools](#️-agent-tools-at-a-glance) for more information.
 
 ### 4. Create your agent
 
+Here is how we will instantiate our AI Finance Assistant. First define your custom instructions:
+
+```python
+financial_assistant_instructions = """
+  - You are a helpful financial assistant, with expertise in financial reporting, in conversation with a user.
+  - Never discuss politics, and always respond politely.
+  - Respond in a compact format by using appropriate units of measure (e.g., K for thousands, M for millions, B for billions).
+  - Do not report the same number twice (e.g. $100K and 100,000 USD).
+  - Always check the get_company_info and get_valid_years tools to validate company and year are valid.
+  - When querying a tool for a numeric value or KPI, use a concise and non-ambiguous description of what you are looking for.
+  - If you calculate a metric, make sure you have all the necessary information to complete the calculation. Don't guess.
+"""
+```
+
+Then just instantiate the `Agent` class:
+
 ```python
 from vectara_agentic import Agent
 
 agent = Agent(
-    tools=[query_financial_reports_tool],
-    topic="10-K financial reports",
-    custom_instructions="""
-        - You are a helpful financial assistant in conversation with a user. Use your financial expertise when crafting a query to the tool, to ensure you get the most accurate information.
-        - You can answer questions, provide insights, or summarize any information from financial reports.
-        - A user may refer to a company's ticker instead of its full name - consider those the same when a user is asking about a company.
-        - When calculating a financial metric, make sure you have all the information from tools to complete the calculation.
-        - In many cases you may need to query tools on each sub-metric separately before computing the final metric.
-        - When using a tool to obtain financial data, consider the fact that information for a certain year may be reported in the following year's report.
-        - Report financial data in a consistent manner. For example if you report revenue in thousands, always report revenue in thousands.
-    """
+    tools = 
+      [ask_finance],
+    topic="10-K annual financial reports",
+    custom_instructions=financial_assistant_instructions,
+    agent_progress_callback=agent_progress_callback
 )
 ```
 
-See the [docs](https://vectara.github.io/py-vectara-agentic/latest/) for additional arguments, including `agent_progress_callback` and `query_logging_callback`.
+The `topic` parameter helps identify the agent's area of expertise, while `custom_instructions` lets you customize how the agent behaves and presents information. The agent will combine these with its default general instructions to determine its complete behavior.
+
+The `agent_progress_callback` argument is an optional function that will be called when various Agent events occur, and can be used to track agent steps.
 
 ### 5. Run a chat interaction
 
@@ -214,93 +246,41 @@ res = agent.chat("What was the revenue for Apple in 2021?")
 print(res.response)
 ```
 
-Note that:
-1. `vectara-agentic` also supports `achat()` and two streaming variants `stream_chat()` and `astream_chat()`.
-2. The response types from `chat()` and `achat()` are of type `AgentResponse`. If you just need the actual string
-   response it's available as the `response` variable, or just use `str()`. For advanced use-cases you can look 
-   at other `AgentResponse` variables [such as `sources`](https://github.com/run-llama/llama_index/blob/659f9faaafbecebb6e6c65f42143c0bf19274a37/llama-index-core/llama_index/core/chat_engine/types.py#L53).
-
-## Advanced Usage: Workflows
-
-In addition to standard chat interactions, `vectara-agentic` supports custom workflows via the `run()` method. 
-Workflows allow you to structure multi-step interactions where inputs and outputs are validated using Pydantic models.
-To learn more about workflows read [the documentation](https://docs.llamaindex.ai/en/stable/understanding/workflows/basic_flow/)
-
-### Defining a Custom Workflow
-
-Create a workflow by subclassing `llama_index.core.workflow.Workflow` and defining the input/output models:
-
-```python
-from pydantic import BaseModel
-from llama_index.core.workflow import (
-    StartEvent,StopEvent, Workflow, step,
-)
-
-class MyWorkflow(Workflow):
-    class InputsModel(BaseModel):
-        query: str
-
-    class OutputsModel(BaseModel):
-        answer: str
-
-    @step
-    async def my_step(self, ev: StartEvent) -> StopEvent:
-        # do something here
-        return StopEvent(result="Hello, world!")
-```
-
-When the `run()` method in vectara-agentic is invoked, it calls the workflow with the following variables in the StartEvent:
-* `agent`: the agent object used to call `run()` (self)
-* `tools`: the tools provided to the agent. Those can be used as needed in the flow.
-* `llm`: a pointer to a LlamaIndex llm, so it can be used in the workflow. For example, one of the steps may call `llm.acomplete(prompt)`
-* `verbose`: controls whether extra debug information is displayed
-* `inputs`: this is the actual inputs to the workflow provided by the call to `run()` and must be of type `InputsModel`
-
-### Using the Workflow with Your Agent
-
-When initializing your agent, pass the workflow class using the `workflow_cls` parameter:
-
-```python
-agent = Agent(
-    tools=[query_financial_reports_tool],
-    topic="10-K financial reports",
-    custom_instructions="You are a helpful financial assistant.",
-    workflow_cls=MyWorkflow,       # Provide your custom workflow here
-    workflow_timeout=120           # Optional: Set a timeout (default is 120 seconds)
-)
-```
+> **Note:** 
+> 1. `vectara-agentic` also supports `achat()` as well as two streaming variants `stream_chat()` and `astream_chat()`.
+> 2. The response types from `chat()` and `achat()` are of type `AgentResponse`. If you just need the actual string
+>    response it's available as the `response` variable, or just use `str()`. For advanced use-cases you can look 
+>    at other `AgentResponse` variables [such as `sources`](https://github.com/run-llama/llama_index/blob/659f9faaafbecebb6e6c65f42143c0bf19274a37/llama-index-core/llama_index/core/chat_engine/types.py#L53).
 
-### Running the Workflow
+## Agent Instructions
 
-Prepare the inputs using your workflow’s `InputsModel` and execute the workflow using `run()`:
+When creating an agent, it already comes with a set of general base instructions, designed carefully to enhance its operation and improve how the agent works.
 
-```python
-# Create an instance of the workflow's input model
-inputs = MyWorkflow.InputsModel(query="What is Vectara?", extra_param=42)
+In addition, you can add `custom_instructions` that are specific to your use case that customize how the agent behaves.
 
-# Run the workflow (ensure you're in an async context or use asyncio.run)
-workflow_result = asyncio.run(agent.run(inputs))
+When writing custom instructions:
+- Focus on behavior and presentation rather than tool usage (that's what tool descriptions are for)
+- Be precise and clear without overcomplicating
+- Consider edge cases and unusual scenarios
+- Avoid over-specifying behavior based on primary use cases
+- Keep instructions focused on how you want the agent to behave and present information
 
-# Access the output from the workflow's OutputsModel
-print(workflow_result.answer)
-```
+The agent will combine both the general instructions and your custom instructions to determine its behavior.
 
-### Using SubQuestionQueryWorkflow
+It is not recommended to change the general instructions, but it is possible as well to override them with the optional `general_instructions` parameter. If you do change them, your agent may not work as intended, so be careful if overriding these instructions.
 
-vectara-agentic already includes one useful workflow you can use right away (it is also useful as an advanced example)
-This workflow is called `SubQuestionQueryWorkflow` and it works by breaking a complex query into sub-queries and then
-executing each sub-query with the agent until it reaches a good response.
+## 🧰 Defining Tools
 
-## 🧰 Vectara tools
+### Vectara tools
 
-`vectara-agentic` provides two helper functions to connect with Vectara RAG
+`vectara-agentic` provides two helper functions to connect with Vectara RAG:
 * `create_rag_tool()` to create an agent tool that connects with a Vectara corpus for querying. 
 * `create_search_tool()` to create a tool to search a Vectara corpus and return a list of matching documents.
 
 See the documentation for the full list of arguments for `create_rag_tool()` and `create_search_tool()`, 
 to understand how to configure Vectara query performed by those tools.
 
-### Creating a Vectara RAG tool
+#### Creating a Vectara RAG tool
 
 A Vectara RAG tool is often the main workhorse for any Agentic RAG application, and enables the agent to query 
 one or more Vectara RAG corpora. 
@@ -310,15 +290,14 @@ metadata filtering, defined by `tool_args_schema`.
 
 For example, in the quickstart example the schema is:
 
-```
+```python
 class QueryFinancialReportsArgs(BaseModel):
-    query: str = Field(..., description="The user query.")
     year: int | str = Field(..., description=f"The year this query relates to. An integer between {min(years)} and {max(years)} or a string specifying a condition on the year (example: '>2020').")
     ticker: str = Field(..., description=f"The company ticker. Must be a valid ticket symbol from the list {tickers.keys()}.")
 ```
 
-The `query` is required and is always the query string.
-The other arguments are optional and will be interpreted as Vectara metadata filters.
+Remember, the `query` argument is part of the rag_tool that is generated, but `vectara-agentic` creates it and you do 
+not need to specify it explicitly. 
 
 For example, in the example above, the agent may call the `query_financial_reports_tool` tool with 
 query='what is the revenue?', year=2022 and ticker='AAPL'. Subsequently the RAG tool will issue
@@ -335,19 +314,20 @@ There are also additional cool features supported here:
 Note that `tool_args_type` is an optional dictionary that indicates the level at which metadata filtering
 is applied for each argument (`doc` or `part`)
 
-### Creating a Vectara search tool
+#### Creating a Vectara search tool
 
 The Vectara search tool allows the agent to list documents that match a query.
 This can be helpful to the agent to answer queries like "how many documents discuss the iPhone?" or other
 similar queries that require a response in terms of a list of matching documents.
 
-## 🛠️ Agent Tools at a Glance
+### 🛠️ Agent Tools at a Glance
 
-`vectara-agentic` provides a few tools out of the box (see ToolsCatalog for details):
+`vectara-agentic` provides a few tools out of the box (see `ToolsCatalog` for details):
 
-1. **Standard tools**: 
+**1. Standard tools**
 - `summarize_text`: a tool to summarize a long text into a shorter summary (uses LLM)
 - `rephrase_text`: a tool to rephrase a given text, given a set of rephrase instructions (uses LLM)
+
 These tools use an LLM and so would use the `Tools` LLM specified in your `AgentConfig`.
 To instantiate them:
 
@@ -359,30 +339,82 @@ summarize_text = ToolsCatalog(agent_config).summarize_text
 This ensures the summarize_text tool is configured with the proper LLM provider and model as 
 specified in the Agent configuration.
 
-2. **Legal tools**: a set of tools for the legal vertical, such as:
+**2. Legal tools**
+A set of tools for the legal vertical, such as:
 - `summarize_legal_text`: summarize legal text with a certain point of view
 - `critique_as_judge`: critique a legal text as a judge, providing their perspective
 
-3. **Financial tools**: based on tools from Yahoo! Finance:
+**3. Financial tools**
+Based on tools from Yahoo! Finance:
 - tools to understand the financials of a public company like: `balance_sheet`, `income_statement`, `cash_flow`
 - `stock_news`: provides news about a company
 - `stock_analyst_recommendations`: provides stock analyst recommendations for a company.
 
-4. **Database tools**: providing tools to inspect and query a database
+**4. Database tools**
+Providing tools to inspect and query a database:
 - `list_tables`: list all tables in the database
 - `describe_tables`: describe the schema of tables in the database
 - `load_data`: returns data based on a SQL query
 - `load_sample_data`: returns the first 25 rows of a table
 - `load_unique_values`: returns the top unique values for a given column
 
-In addition, we include various other tools from LlamaIndex ToolSpecs:
-* Tavily search, EXA.AI and Brave Search
-* arxiv
-* neo4j & Kuzu for Graph DB integration
-* Google tools (including gmail, calendar, and search)
-* Slack
-
-Note that some of these tools may require API keys as environment variables
+**5. Additional integrations**
+vectara-agentic includes various other tools from LlamaIndex ToolSpecs:
+
+* **Search Tools**
+  * Tavily Search: Real-time web search using [Tavily API](https://tavily.com/)
+    ```python
+    from vectara_agentic.tools_catalog import ToolsCatalog
+    tavily_tool = ToolsCatalog(agent_config).tavily_search
+    ```
+  * EXA.AI: Advanced web search and data extraction
+    ```python
+    exa_tool = ToolsCatalog(agent_config).exa_search
+    ```
+  * Brave Search: Web search using Brave's search engine
+    ```python
+    brave_tool = ToolsCatalog(agent_config).brave_search
+    ```
+
+* **Academic Tools**
+  * arXiv: Search and retrieve academic papers
+    ```python
+    arxiv_tool = ToolsCatalog(agent_config).arxiv_search
+    ```
+
+* **Graph Database Tools**
+  * Neo4j: Graph database integration
+    ```python
+    neo4j_tool = ToolsCatalog(agent_config).neo4j_query
+    ```
+  * Kuzu: Lightweight graph database
+    ```python
+    kuzu_tool = ToolsCatalog(agent_config).kuzu_query
+    ```
+
+* **Google Tools**
+  * Gmail: Read and send emails
+    ```python
+    gmail_tool = ToolsCatalog(agent_config).gmail
+    ```
+  * Calendar: Manage calendar events
+    ```python
+    calendar_tool = ToolsCatalog(agent_config).calendar
+    ```
+  * Search: Google search integration
+    ```python
+    google_search_tool = ToolsCatalog(agent_config).google_search
+    ```
+
+* **Communication Tools**
+  * Slack: Send messages and interact with Slack
+    ```python
+    slack_tool = ToolsCatalog(agent_config).slack
+    ```
+
+For detailed setup instructions and API key requirements, please refer the instructions on [LlamaIndex hub](https://llamahub.ai/?tab=tools) for the specific tool.
+
+### Creating custom tools
 
 You can create your own tool directly from a Python function using the `create_tool()` method of the `ToolsFactory` class:
 
@@ -393,165 +425,252 @@ def mult_func(x, y):
 mult_tool = ToolsFactory().create_tool(mult_func)
 ```
 
-Note: When you define your own Python functions as tools, implement them at the top module level,
-and not as nested functions. Nested functions are not supported if you use serialization 
-(dumps/loads or from_dict/to_dict).
+> **Important:** When you define your own Python functions as tools, implement them at the top module level,
+> and not as nested functions. Nested functions are not supported if you use serialization 
+> (dumps/loads or from_dict/to_dict).
 
-## 🛠️ Configuration
-
-## Configuring Vectara-agentic
+### Tool Validation
 
-The main way to control the behavior of `vectara-agentic` is by passing an `AgentConfig` object to your `Agent` when creating it.
-For example:
+When creating an agent, you can enable tool validation by setting `validate_tools=True`. This will check that any tools mentioned in your custom instructions actually exist in the agent's tool set:
 
 ```python
-agent_config = AgentConfig(
-    agent_type = AgentType.REACT,
-    main_llm_provider = ModelProvider.ANTHROPIC,
-    main_llm_model_name = 'claude-3-5-sonnet-20241022',
-    tool_llm_provider = ModelProvider.TOGETHER,
-    tool_llm_model_name = 'meta-llama/Llama-3.3-70B-Instruct-Turbo'
-)
-
 agent = Agent(
-    tools=[query_financial_reports_tool],
-    topic="10-K financial reports",
-    custom_instructions="You are a helpful financial assistant in conversation with a user.",
-    agent_config=agent_config
+    tools=[...],
+    topic="financial reports",
+    custom_instructions="Always use the get_company_info tool first...",
+    validate_tools=True  # Will raise an error if get_company_info tool doesn't exist
 )
 ```
 
-The `AgentConfig` object may include the following items:
-- `agent_type`: the agent type. Valid values are `REACT`, `LLMCOMPILER`, `LATS` or `OPENAI` (default: `OPENAI`).
-- `main_llm_provider` and `tool_llm_provider`: the LLM provider for main agent and for the tools. Valid values are `OPENAI`, `ANTHROPIC`, `TOGETHER`, `GROQ`, `COHERE`, `BEDROCK`, `GEMINI` or `FIREWORKS` (default: `OPENAI`).
-- `main_llm_model_name` and `tool_llm_model_name`: agent model name for agent and tools (default depends on provider).
-- `observer`: the observer type; should be `ARIZE_PHOENIX` or if undefined no observation framework will be used.
-- `endpoint_api_key`: a secret key if using the API endpoint option (defaults to `dev-api-key`)
-- `max_reasoning_steps`: the maximum number of reasoning steps (iterations for React and function calls for OpenAI agent, respectively). Defaults to 50.
+This helps catch errors where your instructions reference tools that aren't available to the agent.
 
-If any of these are not provided, `AgentConfig` first tries to read the values from the OS environment.
+## 🔄 Advanced Usage: Workflows
 
-## Configuring Vectara tools: rag_tool, or search_tool
+In addition to standard chat interactions, `vectara-agentic` supports custom workflows via the `run()` method. 
+Workflows allow you to structure multi-step interactions where inputs and outputs are validated using Pydantic models.
+To learn more about workflows read [the documentation](https://docs.llamaindex.ai/en/stable/understanding/workflows/basic_flow/)
 
-When creating a `VectaraToolFactory`, you can pass in a `vectara_api_key`, and `vectara_corpus_key` to the factory. 
+### What are Workflows?
 
-If not passed in, it will be taken from the environment variables (`VECTARA_API_KEY` and `VECTARA_CORPUS_KEY`). Note that `VECTARA_CORPUS_KEY` can be a single KEY or a comma-separated list of KEYs (if you want to query multiple corpora).
+Workflows provide a structured way to handle complex, multi-step interactions with your agent. They're particularly useful when:
 
-These values will be used as credentials when creating Vectara tools - in `create_rag_tool()` and `create_search_tool()`.
+- You need to break down complex queries into simpler sub-questions
+- You want to implement a specific sequence of operations
+- You need to maintain state between different steps of a process
+- You want to parallelize certain operations for better performance
 
-## Setting up a privately hosted LLM
+### Defining a Custom Workflow
 
-If you want to setup vectara-agentic to use your own self-hosted LLM endpoint, follow the example below
+Create a workflow by subclassing `llama_index.core.workflow.Workflow` and defining the input/output models:
 
 ```python
-        config = AgentConfig(
-            agent_type=AgentType.REACT,
-            main_llm_provider=ModelProvider.PRIVATE,
-            main_llm_model_name="meta-llama/Meta-Llama-3.1-8B-Instruct",
-            private_llm_api_base="http://vllm-server.company.com/v1",
-            private_llm_api_key="TEST_API_KEY",
-        )
-        agent = Agent(agent_config=config, tools=tools, topic=topic,
-                      custom_instructions=custom_instructions)
-```
+from pydantic import BaseModel
+from llama_index.core.workflow import (
+    StartEvent, StopEvent, Workflow, step,
+)
 
-In this case we specify the Main LLM provider to be privately hosted with Llama-3.1-8B as the model.
-- The `ModelProvider.PRIVATE` specifies a privately hosted LLM.
-- The `private_llm_api_base` specifies the api endpoint to use, and the `private_llm_api_key`
-  specifies the private API key requires to use this service.
+class MyWorkflow(Workflow):
+    class InputsModel(BaseModel):
+        query: str
 
-## ℹ️ Additional Information
+    class OutputsModel(BaseModel):
+        answer: str
 
-### About Custom Instructions for your Agent
+    @step
+    async def my_step(self, ev: StartEvent) -> StopEvent:
+        # do something here
+        return StopEvent(result="Hello, world!")
+```
 
-The custom instructions you provide to the agent guide its behavior.
-Here are some guidelines when creating your instructions:
-- Write precise and clear instructions, without overcomplicating.
-- Consider edge cases and unusual or atypical scenarios.
-- Be cautious to not over-specify behavior based on your primary use-case, as it may limit the agent's ability to behave properly in others.
+When the `run()` method in vectara-agentic is invoked, it calls the workflow with the following variables in the `StartEvent`:
+* `agent`: the agent object used to call `run()` (self)
+* `tools`: the tools provided to the agent. Those can be used as needed in the flow.
+* `llm`: a pointer to a LlamaIndex llm, so it can be used in the workflow. For example, one of the steps may call `llm.acomplete(prompt)`
+* `verbose`: controls whether extra debug information is displayed
+* `inputs`: this is the actual inputs to the workflow provided by the call to `run()` and must be of type `InputsModel`
 
-###  Diagnostics
+If you want to use `agent`, `tools`, `llm` or `verbose` in other events (that are not `StartEvent`), you can store them in
+the `Context` of the Workflow as follows:
 
-The `Agent` class defines a few helpful methods to help you understand the internals of your application. 
-* The `report()` method prints out the agent object’s type, the tools, and the LLMs used for the main agent and tool calling.
-* The `token_counts()` method tells you how many tokens you have used in the current session for both the main agent and tool calling LLMs. This can be helpful if you want to track spend by token.
+```python
+await ctx.set("agent", ev.agent)
+```
 
-###  Serialization
+and then in any other event you can pull that agent object with
 
-The `Agent` class supports serialization. Use the `dumps()` to serialize and `loads()` to read back from a serialized stream.
+```python
+agent = await ctx.get("agent")
+```
 
-Note: due to cloudpickle limitations, if a tool contains Python `weakref` objects, serialization won't work and an exception will be raised.
+Similarly you can reuse the `llm`, `tools` or `verbose` arguments within other nodes in the workflow.
 
-###  Observability
+### Using the Workflow with Your Agent
 
-vectara-agentic supports observability via the existing integration of LlamaIndex and Arize Phoenix.
-First, set `VECTARA_AGENTIC_OBSERVER_TYPE` to `ARIZE_PHOENIX` in `AgentConfig` (or env variable).
+When initializing your agent, pass the workflow class using the `workflow_cls` parameter:
 
-Then you can use Arize Phoenix in three ways: 
-1. **Locally**. 
-   1. If you have a local phoenix server that you've run using e.g. `python -m phoenix.server.main serve`, vectara-agentic will send all traces to it.
-   2. If not, vectara-agentic will run a local instance during the agent's lifecycle, and will close it when finished.
-   3. In both cases, traces will be sent to the local instance, and you can see the dashboard at `http://localhost:6006`
-2. **Hosted Instance**. In this case the traces are sent to the Phoenix instances hosted on Arize.
-   1. Go to `https://app.phoenix.arize.com`, setup an account if you don't have one.
-   2. create an API key and put it in the `PHOENIX_API_KEY` environment variable - this indicates you want to use the hosted version.
-   3. To view the traces go to `https://app.phoenix.arize.com`.
+```python
+agent = Agent(
+    tools=[query_financial_reports_tool],
+    topic="10-K financial reports",
+    custom_instructions="You are a helpful financial assistant.",
+    workflow_cls=MyWorkflow,       # Provide your custom workflow here
+    workflow_timeout=120           # Optional: Set a timeout (default is 120 seconds)
+)
+```
 
-Now when you run your agent, all call traces are sent to Phoenix and recorded. 
-In addition, vectara-agentic also records `FCS` (factual consistency score, aka HHEM) values into Arize for every Vectara RAG call. You can see those results in the `Feedback` column of the arize UI.
+### Running the Workflow
 
-## 🌐 API Endpoint
+Prepare the inputs using your workflow's `InputsModel` and execute the workflow using `run()`:
 
-`vectara-agentic` can be easily hosted locally or on a remote machine behind an API endpoint, by following theses steps:
+```python
+# Create an instance of the workflow's input model
+inputs = MyWorkflow.InputsModel(query="What is Vectara?", extra_param=42)
 
-### Step 1: Setup your API key
-Ensure that you have your API key set up as an environment variable:
+# Run the workflow (ensure you're in an async context or use asyncio.run)
+workflow_result = asyncio.run(agent.run(inputs))
 
+# Access the output from the workflow's OutputsModel
+print(workflow_result.answer)
 ```
-export VECTARA_AGENTIC_API_KEY=<YOUR-ENDPOINT-API-KEY>
-```
 
-if you don't specify an Endpoint API key it uses the default "dev-api-key".
+### Built-in Workflows
+
+`vectara-agentic` includes two workflow implementations that you can use right away:
 
-### Step 2: Start the API Server
-Initialize the agent and start the FastAPI server by following this example:
+#### 1. `SubQuestionQueryWorkflow`
 
+This workflow breaks down complex queries into simpler sub-questions, executes them in parallel, and then combines the answers:
 
+```python
+from vectara_agentic.sub_query_workflow import SubQuestionQueryWorkflow
+
+agent = Agent(
+    tools=[query_financial_reports_tool],
+    topic="10-K financial reports",
+    custom_instructions="You are a helpful financial assistant.",
+    workflow_cls=SubQuestionQueryWorkflow
+)
+
+# Run the workflow with a complex query
+inputs = SubQuestionQueryWorkflow.InputsModel(
+    query="Compare Apple's revenue growth to Google's between 2020 and 2023"
+)
+result = asyncio.run(agent.run(inputs))
+print(result.response)
 ```
-from vectara_agentic.agent import Agent
-from vectara_agentic.agent_endpoint import start_app
-agent = Agent(...)            # Initialize your agent with appropriate parameters
-start_app(agent)
+
+The workflow works in three steps:
+1. **Query**: Breaks down the complex query into sub-questions
+2. **Sub-question**: Executes each sub-question in parallel (using 4 workers by default)
+3. **Combine answers**: Synthesizes all the answers into a coherent response
+
+#### 2. `SequentialSubQuestionsWorkflow`
+
+This workflow is similar to `SubQuestionQueryWorkflow` but executes sub-questions sequentially, where each question can depend on the answer to the previous question:
+
+```python
+from vectara_agentic.sub_query_workflow import SequentialSubQuestionsWorkflow
+
+agent = Agent(
+    tools=[query_financial_reports_tool],
+    topic="10-K financial reports",
+    custom_instructions="You are a helpful financial assistant.",
+    workflow_cls=SequentialSubQuestionsWorkflow
+)
+
+# Run the workflow with a complex query that requires sequential reasoning
+inputs = SequentialSubQuestionsWorkflow.InputsModel(
+    query="What was the revenue growth rate of the company with the highest market cap in 2022?"
+)
+result = asyncio.run(agent.run(inputs))
+print(result.response)
 ```
 
-You can customize the host and port by passing them as arguments to `start_app()`:
-* Default: host="0.0.0.0" and port=8000.
+The workflow works in two steps:
+1. **Query**: Breaks down the complex query into sequential sub-questions
+2. **Sub-question**: Executes each sub-question in sequence, passing the answer from one question to the next
+
+### When to Use Each Workflow Type
+
+- **Use SubQuestionQueryWorkflow** when:
+  - Your query can be broken down into independent sub-questions
+  - You want to parallelize the execution for better performance
+  - The sub-questions don't depend on each other's answers
+
+- **Use SequentialSubQuestionsWorkflow** when:
+  - Your query requires sequential reasoning
+  - Each sub-question depends on the answer to the previous question
+  - You need to build up information step by step
+
+- **Create a custom workflow** when:
+  - You have a specific sequence of operations that doesn't fit the built-in workflows
+  - You need to implement complex business logic
+  - You want to integrate with external systems or APIs in a specific way
+
+## 🛠️ Configuration
+
+### Configuring Vectara-agentic
+
+The main way to control the behavior of `vectara-agentic` is by passing an `AgentConfig` object to your `Agent` when creating it.
 For example:
-```
-start_app(agent, host="0.0.0.0", port=8000)
-```
 
-### Step 3: Access the API Endpoint
-Once the server is running, you can interact with it using curl or any HTTP client. For example:
+```python
+from vectara_agentic import AgentConfig, AgentType, ModelProvider
 
-```
-curl -G "http://<remote-server-ip>:8000/chat" \
---data-urlencode "message=What is Vectara?" \
--H "X-API-Key: <YOUR-ENDPOINT-API-KEY>"
+agent_config = AgentConfig(
+    agent_type = AgentType.REACT,
+    main_llm_provider = ModelProvider.ANTHROPIC,
+    main_llm_model_name = 'claude-3-5-sonnet-20241022',
+    tool_llm_provider = ModelProvider.TOGETHER,
+    tool_llm_model_name = 'meta-llama/Llama-3.3-70B-Instruct-Turbo'
+)
+
+agent = Agent(
+    tools=[query_financial_reports_tool],
+    topic="10-K financial reports",
+    custom_instructions="You are a helpful financial assistant in conversation with a user.",
+    agent_config=agent_config
+)
 ```
 
-## 🤝 Contributing
+The `AgentConfig` object may include the following items:
+- `agent_type`: the agent type. Valid values are `REACT`, `LLMCOMPILER`, `LATS` or `OPENAI` (default: `OPENAI`).
+- `main_llm_provider` and `tool_llm_provider`: the LLM provider for main agent and for the tools. Valid values are `OPENAI`, `ANTHROPIC`, `TOGETHER`, `GROQ`, `COHERE`, `BEDROCK`, `GEMINI` or `FIREWORKS` (default: `OPENAI`).
+- `main_llm_model_name` and `tool_llm_model_name`: agent model name for agent and tools (default depends on provider).
+- `observer`: the observer type; should be `ARIZE_PHOENIX` or if undefined no observation framework will be used.
+- `endpoint_api_key`: a secret key if using the API endpoint option (defaults to `dev-api-key`)
+- `max_reasoning_steps`: the maximum number of reasoning steps (iterations for React and function calls for OpenAI agent, respectively). Defaults to 50.
 
-We welcome contributions! Please see our [contributing guide](https://github.com/vectara/py-vectara-agentic/blob/main/CONTRIBUTING.md) for more information.
+If any of these are not provided, `AgentConfig` first tries to read the values from the OS environment.
 
-## 📝 License
+### Configuring Vectara tools: `rag_tool`, or `search_tool`
 
-This project is licensed under the Apache 2.0 License. See the [LICENSE](https://github.com/vectara/py-vectara-agentic/blob/master/LICENSE) file for details.
+When creating a `VectaraToolFactory`, you can pass in a `vectara_api_key`, and `vectara_corpus_key` to the factory. 
+
+If not passed in, it will be taken from the environment variables (`VECTARA_API_KEY` and `VECTARA_CORPUS_KEY`). Note that `VECTARA_CORPUS_KEY` can be a single KEY or a comma-separated list of KEYs (if you want to query multiple corpora).
+
+These values will be used as credentials when creating Vectara tools - in `create_rag_tool()` and `create_search_tool()`.
+
+### Setting up a privately hosted LLM
+
+If you want to setup `vectara-agentic` to use your own self-hosted LLM endpoint, follow the example below:
 
-## 📞 Contact
+```python
+from vectara_agentic import AgentConfig, AgentType, ModelProvider
+
+config = AgentConfig(
+    agent_type=AgentType.REACT,
+    main_llm_provider=ModelProvider.PRIVATE,
+    main_llm_model_name="meta-llama/Meta-Llama-3.1-8B-Instruct",
+    private_llm_api_base="http://vllm-server.company.com/v1",
+    private_llm_api_key="TEST_API_KEY",
+)
+
+agent = Agent(
+    agent_config=config, 
+    tools=tools, 
+    topic=topic,
+    custom_instructions=custom_instructions
+)
+```
 
-- Website: [vectara.com](https://vectara.com)
-- Twitter: [@vectara](https://twitter.com/vectara)
-- GitHub: [@vectara](https://github.com/vectara)
-- LinkedIn: [@vectara](https://www.linkedin.com/company/vectara/)
-- Discord: [Join our community](https://discord.gg/GFb8gMz6UH)