Temporal AI Agent Framework

A powerful, scalable framework for building and running conversational AI agents using the Temporal.io workflow engine. This framework provides a robust foundation for creating durable, observable, and stateful agents that can execute complex tasks and interact with external tools.

Core Features

• Workflow-as-Agent: Models agentic logic as durable, stateful, and observable Temporal workflows. The state, history, and execution logic of your agent are preserved even across failures and server restarts.
• Retrieval-Augmented Generation (RAG): Includes a built-in DataIngestionWorkflow to scrape websites, create vector embeddings, and build a knowledge base in ChromaDB. Agents can then use the KnowledgeSearch tool to query this database for context-aware responses.
• Stateful & Stateless Conversation Models:
  • ConversationalAgentWorkflowStateful: A long-running, persistent agent that maintains conversation history across multiple interactions. Ideal for building chatbots and personal assistants.
  • ConversationalAgentWorkflow: A stateless agent designed for single-purpose, "one-shot" tasks and queries.
• Extensible Tool Use: Easily add new tools for your agents by implementing them as Temporal Activities. The framework includes a KnowledgeSearch tool and a pattern for discovering and executing tools from a remote "Multi-Capability Platform" (MCPAgentWorkflow).
• Multiple Interfaces: Interact with your agents through various channels:
  • REST API: A FastAPI server exposes endpoints for seamless integration with web applications.
  • Interactive CLI: A user-friendly command-line interface for direct conversation with an agent.
  • Workflow Execution Scripts: Run and test workflows directly for development and batch processing.

Project Structure

File	Description
main.py	FastAPI application exposing agent workflows via a REST API.
worker.py	The main Temporal Worker. This process hosts and executes all workflow and activity logic.
workflows.py	Contains the definitions for the stateless DataIngestionWorkflow and ConversationalAgentWorkflow.
workflow_stateful.py	Defines the long-running, stateful ConversationalAgentWorkflowStateful.
activities.py	Implementations of the core logic units (tools) that workflows orchestrate, such as scraping, database search, and LLM calls.
run_workflow.py	A command-line script to trigger the stateless workflows.
run_stateful_workflow.py	A command-line client to interact with the stateful conversational agent.
cli_app.py	An interactive CLI application for a continuous chat session.
requirements.txt	A list of all the Python dependencies for the project.
interfaces.py	Defines the data structures (dataclasses) used for passing data between workflows and activities.
llm_client.py / gcp_client.py	Clients for interacting with Large Language Models (e.g., Google Gemini).
db_client.py	A client for interacting with the ChromaDB vector database.

Getting Started

1. Prerequisites

• Python 3.8+
• A running Temporal Server instance. You can run one locally using Docker:

  git clone https://github.com/temporalio/docker-compose.git
  cd docker-compose
  docker-compose up -d

2. Installation

1. Clone the repository:

   git clone <your-repo-url>
   cd temporal_agent_endpoint

2. Install dependencies:

   pip install -r requirements.txt

3. Set up environment variables: This project uses a .env file for configuration. You will need to create one for your LLM provider credentials.

   # Example for Google AI (Gemini)
   touch .env
   echo "GOOGLE_API_KEY='your-google-api-key'" >> .env

3. Running the Agent Framework

The system runs in three stages: start the worker, populate the knowledge base, and interact with an agent.

Step 1: Start the Temporal Worker

The worker is the engine that executes your code. It must be running to process any workflow or activity.

python worker.py

You will be prompted to enter a name, company, and personality for the assistant. You can press Enter to accept the defaults. The worker will then connect to the Temporal server and start listening for tasks.

Step 2: Populate the Knowledge Base (Optional)

To enable the RAG capabilities, you first need to ingest data. Run the DataIngestionWorkflow with a list of URLs.

python run_workflow.py ingest --urls https://www.ganni.com/us/en/help/faq.html

This command starts a workflow that scrapes the provided URLs and stores their content in the ChromaDB vector store.

Step 3: Interact with an Agent

You can now interact with an agent through the API or the CLI.

Option A: Interactive CLI

For a continuous, interactive chat session:

python cli_app.py

This script will first prompt you for URLs to ingest and then drop you into a chat loop with the agent.

Option B: FastAPI REST API

For integration with other services, start the FastAPI server:

uvicorn main:app --reload

You can now send requests to the agent. The API documentation is available at http://127.0.0.1:8000/docs.

Example curl command:

curl -X POST "http://127.0.0.1:8000/agent" \
     -H "Content-Type: application/json" \
     -d 
     {
           "query": "Can I exchange an item I bought online?"
         }

Option C: Stateful Conversation CLI

To start and interact with a long-running, stateful agent:

1. Start the workflow:

   python run_stateful_workflow.py start

   This will print a unique workflow_id for the conversation.

2. Send messages:

   python run_stateful_workflow.py chat --workflow-id <your-workflow-id> --message "Hello, who are you?"

3. View history:

   python run_stateful_workflow.py query --workflow-id <your-workflow-id>

4. End the conversation:

   python run_stateful_workflow.py stop --workflow-id <your-workflow-id>