Weknora/Enterprise-Knowledge-Base

Fork 0

Files

T

wizardchen 4fa3adbf3b feat: Add agent configuration and cleanup scripts for database migrations

2025-11-05 23:18:44 +08:00

7.3 KiB

Raw Blame History

Quick Start Guide

Get started with the WeKnora Agent Test Tool in 5 minutes!

Prerequisites

Go 1.21 or higher
Access to a running WeKnora instance
A knowledge base ID (or create one through the tool)

Quick Start

Option 1: Using the Build Script (Recommended)

# 1. Navigate to the tool directory
cd client/cmd/agent_test

# 2. Build and run with your knowledge base
./run.sh -k kb_your_knowledge_base_id

# Or with a remote server
./run.sh -u https://api.weknora.com -k kb_12345 -t your_token

Option 2: Using Make

# Build the binary
make build

# Run with environment variables
KB_ID=kb_12345 make run-local

# Or run the binary directly
./agent_test -url http://localhost:8080 -kb kb_12345

Option 3: Direct Go Build

# Build
go build -o agent_test .

# Run
./agent_test -url http://localhost:8080 -kb kb_your_knowledge_base_id

First Steps

Once the tool is running, you'll see an interactive prompt:

╔════════════════════════════════════════════════════════════╗
║         WeKnora Agent QA Testing Tool                     ║
╚════════════════════════════════════════════════════════════╝

[No Session] >

1. Create a New Session

> new

The tool will create a new session and show you the session ID.

2. Ask Your First Question

[Session: abc12345] > ask What is machine learning?

You'll see real-time output showing:

💭 Agent thinking process
🔧 Tool calls (if any)
📚 Knowledge references
📝 Final answer
🤔 Reflections (if any)

3. Continue the Conversation

[Session: abc12345] > ask Can you give me examples?
[Session: abc12345] > ask How does it work?

4. View Session Info

[Session: abc12345] > info

5. List All Sessions

[Session: abc12345] > sessions

6. Exit

[Session: abc12345] > exit

Command Reference

Command	Description	Example
`new`	Create a new session	`> new`
`ask <query>`	Ask the agent a question	`> ask What is AI?`
`info`	Show current session details	`> info`
`sessions`	List all your sessions	`> sessions`
`switch <id>`	Switch to another session	`> switch sess_123`
`help`	Show help message	`> help`
`exit` or `quit`	Exit the program	`> exit`

Example Session

$ ./run.sh -k kb_ml_docs

[No Session] > new
✓ Session created successfully!
  Session ID: sess_a1b2c3d4
  Knowledge Base: kb_ml_docs
  Created At: 2025-11-03T10:00:00Z

[Session: sess_a1b] > ask What is a neural network?

╔═══ Agent Processing ═══╗
Query: What is a neural network?

💭 Thinking: I need to search the knowledge base for information about neural networks...

🔧 Tool Call: search_knowledge
   Arguments: map[query:neural network definition]

✓ Tool Result:
   Found 3 relevant knowledge chunks

📚 Knowledge References: Found 3 reference(s)
   1. [Score: 0.892] A neural network is a series of algorithms...
      Knowledge: Neural Networks 101 (Chunk: 2)
   2. [Score: 0.856] Neural networks mimic biological neurons...
      Knowledge: Deep Learning Basics (Chunk: 5)
   3. [Score: 0.834] The structure consists of layers...
      Knowledge: ML Architectures (Chunk: 8)

📝 Final Answer:
A neural network is a computing system inspired by biological neural networks 
in animal brains. It consists of interconnected nodes (artificial neurons) 
organized in layers that process information using a connectionist approach 
to computation. Neural networks learn to perform tasks by considering examples, 
generally without being programmed with task-specific rules.

🤔 Reflection: I successfully found relevant information in the knowledge base 
and provided a comprehensive answer covering the definition, structure, and 
learning mechanism of neural networks.

╔═══ Summary ═══╗
Duration: 2.34s
Tool Calls: 1 (search_knowledge)
References: 3
Reflections: 1
╚═══════════════╝

[Session: sess_a1b] > ask What are the main types?

╔═══ Agent Processing ═══╗
Query: What are the main types?

💭 Thinking: The user is asking about types of neural networks based on the 
previous context...

[... continuing the conversation ...]

Testing Scenarios

We provide a test scenarios script for common testing patterns:

# Run interactive scenario menu
./test_scenarios.sh

# Run a specific scenario
./test_scenarios.sh 1  # Basic Q&A
./test_scenarios.sh 2  # Complex queries
./test_scenarios.sh 3  # Multi-turn conversation

Configuration with Environment Variables

Create a configuration file for repeated use:

# Create config file
cat > config.env << EOF
export WEKNORA_URL=http://localhost:8080
export WEKNORA_KB_ID=kb_your_knowledge_base_id
export WEKNORA_TOKEN=your_token_if_needed
EOF

# Load and run
source config.env
./run.sh

Troubleshooting

"Connection refused"

Make sure WeKnora server is running
Check the URL is correct
Verify network connectivity

"Knowledge base not found"

Verify your knowledge base ID is correct
Check you have access to the knowledge base
Ensure the knowledge base has been initialized

"Session not found"

The session may have expired or been deleted
Create a new session with new command

No tool calls happening

Check your knowledge base has content
Verify the agent configuration includes tool definitions
Look for error messages in the output

Advanced Usage

Using with Docker

If WeKnora is running in Docker:

# Get the container's IP or use host networking
./agent_test -url http://localhost:8080 -kb kb_123

Testing with Production

# Use production URL with authentication
./agent_test \
  -url https://api.weknora.com \
  -token $PROD_TOKEN \
  -kb kb_prod_123

Continuing an Existing Session

# Skip session creation and continue existing one
./agent_test -url http://localhost:8080 -session sess_existing_id

Batch Testing

# Pipe commands for automated testing
echo -e "new\nask What is AI?\ninfo\nexit" | ./agent_test -url http://localhost:8080 -kb kb_123

Next Steps

Read the full README.md for detailed documentation
Check agent_example.go for code examples
Explore the client package documentation
Review agent events and response types in the main README

Getting Help

If you encounter issues:

Check the README.md for detailed documentation
Review the error messages - they usually indicate the problem
Verify your configuration (URL, KB ID, token)
Check WeKnora server logs for backend issues
Use info command to check session state

Tips

Start Simple: Begin with basic questions to verify connectivity
Use Info: The info command shows valuable session configuration
Watch Events: Pay attention to all event types to understand agent behavior
Check References: Knowledge references show if retrieval is working correctly
Monitor Performance: The summary shows timing and tool usage statistics

Happy testing! 🚀

7.3 KiB Raw Blame History