orka
Request AccessSign In

Creating Agents

This guide walks you through the process of creating and configuring an AI agent in Orka. You'll learn how to customize agent behavior, connect datastores, and optimize for your use case.

Overview

An agent in Orka is an AI-powered interface that can:

  • Answer questions based on your documents
  • Follow specific instructions and personas
  • Provide cited, verifiable responses
  • Maintain conversation context

Creating Your First Agent

Using the Dashboard

The agent creation wizard guides you through a 12-step configuration process. Navigate to Agents in the sidebar and click Create Agent to begin.

Step 1: General

Basic information about your agent:

  • Name: A descriptive name (e.g., "Customer Support Agent")
  • Description: What this agent is for

Step 2: Datastores

Connect data sources to your agent:

  • Create new: Create a new datastore and upload documents
  • Link existing: Connect to an existing datastore in your workspace

Step 3: System Prompts (Coming Soon)

Configure the core behavior prompts:

  • Core System Prompt: Main instructions that define agent behavior
  • No Retrieval System Prompt: Instructions used when no documents are retrieved

Step 4: Query Understanding (Coming Soon)

Control how the agent interprets queries:

  • Check Retrieval Need: Determine if a query requires document retrieval
  • Multi-turn Conversations: Enable context from previous messages

Step 5: Query Reformulation (Coming Soon)

Improve query accuracy:

  • Enable Query Reformulation: Rewrite queries for better retrieval

Step 6: Retrieval (Coming Soon)

Configure document retrieval settings:

  • Top K Results: Number of chunks to retrieve (1-50)
  • Similarity Threshold: Minimum relevance score (0.0-1.0)

Step 7: Rerank (Coming Soon)

Apply neural reranking to improve results:

  • Enable Reranking: Apply a reranker model to retrieved chunks
  • Reranker Model: Select the reranking model to use

Step 8: Filter (Coming Soon)

Apply metadata filters to retrieval:

  • Filter Configuration: JSON-based filter rules for document metadata

Step 9: Generation (Coming Soon)

Configure response generation:

  • Model: Select the LLM model (e.g., GPT-4, Claude)
  • Temperature: Creativity level (0.0-2.0)
  • Max Tokens: Maximum response length

Step 10: Translation (Coming Soon)

Enable multi-language support:

  • Enable Translation: Auto-translate queries and responses

Step 11: User Experience (Coming Soon)

Configure response delivery:

  • Streaming: Enable streaming responses
  • Citation Format: How citations appear in responses

Step 12: Feedback Annotation (Coming Soon)

Enable user feedback collection:

  • Feedback Collection: Allow users to rate responses

Steps marked "Coming Soon" are visible in the wizard but not yet configurable. Default values are applied automatically.

Using the API

javascript
1const agent = await client.agents.create({
2  name: 'Customer Support Agent',
3  description: 'Answers questions about our products and services',
4});

Configuring the System Prompt

The system prompt is the most important configuration for your agent. It defines how the agent behaves, responds, and what persona it adopts.

Basic System Prompt

text
You are a helpful customer support agent for Acme Corp.
Answer questions about our products accurately and professionally.
Always cite your sources when providing information from documents.

Advanced System Prompt

text
You are a senior customer support specialist for Acme Corp.

## Your Role
- Answer questions about our products, pricing, and policies
- Help troubleshoot common issues
- Escalate complex issues appropriately

## Guidelines
- Be professional but friendly
- Keep responses concise (under 200 words unless detail is needed)
- Always cite sources using [1], [2], etc.
- If you don't know something, say so clearly
- Never make up information not in the documents

## Response Format
1. Direct answer to the question
2. Supporting details if needed
3. Relevant citations
4. Follow-up suggestion if appropriate

System Prompt Best Practices

  • Be specific about the agent's role and boundaries
  • Include formatting guidelines for consistent responses
  • Define how to handle edge cases (unknown information, off-topic questions)
  • Test and iterate based on actual responses

Connecting Datastores

Agents need datastores to provide document-grounded responses.

Single Datastore

For focused use cases, connect a single datastore:

javascript
1await client.agents.connectDatastore({
2  agent_id: agent.id,
3  datastore_id: 'ds_products',
4});

Multiple Datastores

For broader knowledge, connect multiple datastores:

javascript
1// Connect product documentation
2await client.agents.connectDatastore({
3  agent_id: agent.id,
4  datastore_id: 'ds_products',
5});
6
7// Connect FAQs
8await client.agents.connectDatastore({
9  agent_id: agent.id,
10  datastore_id: 'ds_faqs',
11});
12
13// Connect policies
14await client.agents.connectDatastore({
15  agent_id: agent.id,
16  datastore_id: 'ds_policies',
17});

When an agent has multiple datastores, it searches all of them and returns the most relevant results regardless of which datastore they come from.

Agent Settings

Fine-tune your agent's behavior with these settings:

Temperature

Controls creativity vs consistency:

| Value | Behavior | |-------|----------| | 0.0 - 0.3 | Very consistent, factual responses | | 0.4 - 0.7 | Balanced (recommended for most use cases) | | 0.8 - 1.0 | More creative, varied responses |

javascript
1await client.agents.update(agent.id, {
2  settings: {
3    temperature: 0.5,
4  },
5});

Retrieval Count

Number of document chunks to retrieve per query:

| Value | Use Case | |-------|----------| | 3-5 | Quick, focused answers | | 5-10 | Comprehensive answers (default) | | 10-20 | Research-heavy queries |

javascript
1await client.agents.update(agent.id, {
2  settings: {
3    retrieval_count: 10,
4  },
5});

Max Tokens

Maximum response length:

javascript
1await client.agents.update(agent.id, {
2  settings: {
3    max_tokens: 1024, // ~750 words
4  },
5});

Testing Your Agent

Before deploying, test your agent thoroughly:

Test Basic Queries

javascript
1const response = await client.chat.query({
2  agent_id: agent.id,
3  message: 'What products do you offer?',
4});
5
6console.log(response.content);
7console.log('Citations:', response.citations.length);

Test Edge Cases

  1. Questions outside document scope: Should acknowledge limitations
  2. Ambiguous questions: Should ask for clarification or provide options
  3. Follow-up questions: Should maintain context
  4. Complex multi-part questions: Should address all parts

Test Conversation Flow

javascript
1// First question
2const r1 = await client.chat.query({
3  agent_id: agent.id,
4  message: 'What is your return policy?',
5});
6
7// Follow-up
8const r2 = await client.chat.query({
9  agent_id: agent.id,
10  conversation_id: r1.conversation_id,
11  message: 'How long do I have to return items?',
12});

Use Case Examples

Customer Support Agent

javascript
1const supportAgent = await client.agents.create({
2  name: 'Support Assistant',
3  system_prompt: `You are a customer support assistant.
4Answer questions about products, orders, and policies.
5Be helpful and empathetic. Always cite your sources.`,
6  settings: {
7    temperature: 0.5,
8    retrieval_count: 8,
9  },
10});

Research Assistant

javascript
1const researchAgent = await client.agents.create({
2  name: 'Research Assistant',
3  system_prompt: `You are a research assistant that helps analyze documents.
4Provide thorough, well-cited answers.
5Compare information from multiple sources when relevant.
6Highlight any conflicting information you find.`,
7  settings: {
8    temperature: 0.3,
9    retrieval_count: 15,
10    max_tokens: 2048,
11  },
12});

Internal Knowledge Base

javascript
1const kbAgent = await client.agents.create({
2  name: 'Company Knowledge Base',
3  system_prompt: `You are an internal knowledge assistant.
4Help employees find information about company policies, procedures, and resources.
5Be concise and direct. Link to relevant documents when possible.`,
6  settings: {
7    temperature: 0.4,
8    retrieval_count: 5,
9  },
10});

Next Steps