orka
Request AccessSign In

Quickstart

Build an AI agent that reasons about your business data. By the end of this guide, you'll have an agent that doesn't just retrieve documents—it understands them.

What You'll Build

  1. An AI agent with reasoning capabilities
  2. A datastore with your documents
  3. Logic definitions that encode your domain knowledge
  4. A query that returns answers you can actually use

Step 1: Create an Agent

Create an agent that will reason about your documents:

javascript
1const agent = await client.agents.create({
2  name: 'Contract Analyst',
3  description: 'An agent that reasons about contracts and business agreements',
4  system_prompt: 'You are a contract analyst. Answer questions by reasoning about the documents and applying business rules. Always cite your sources.',
5});
6
7console.log('Agent created:', agent.id);

Agents can be customized with specific behaviors, reasoning approaches, and response formats. See the Creating Agents guide for advanced configuration.

Step 2: Create a Datastore

Datastores hold the documents your agent reasons about:

javascript
1const datastore = await client.datastores.create({
2  name: 'Contracts',
3  description: 'Collection of business contracts and agreements',
4});
5
6console.log('Datastore created:', datastore.id);

Step 3: Upload Documents

Upload documents to your datastore. Orka supports PDF, DOCX, TXT, and more.

javascript
1const document = await client.documents.upload({
2  datastore_id: datastore.id,
3  file: fs.createReadStream('./contract.pdf'),
4  name: 'Acme Corp Agreement',
5});
6
7console.log('Document uploaded:', document.id);
8console.log('Processing status:', document.status);

Processing Time

Documents need to be processed before they can be queried. This typically takes a few seconds to a few minutes depending on document size.

Check Processing Status

Wait for the document to finish processing:

javascript
1async function waitForProcessing(documentId) {
2  while (true) {
3    const doc = await client.documents.get(documentId);
4
5    if (doc.status === 'completed') {
6      console.log('Document ready!');
7      return doc;
8    }
9
10    if (doc.status === 'failed') {
11      throw new Error('Document processing failed');
12    }
13
14    console.log('Processing...', doc.status);
15    await new Promise(r => setTimeout(r, 2000));
16  }
17}
18
19await waitForProcessing(document.id);

Step 4: Connect Agent to Datastore

Link your agent to the datastore so it can access the documents:

javascript
1await client.agents.connectDatastore({
2  agent_id: agent.id,
3  datastore_id: datastore.id,
4});
5
6console.log('Agent connected to datastore');

Step 5: Add Logic Definitions

This is where Orka differs from basic RAG. Define logic (metrics, terms, and rules) so your agent understands your domain:

javascript
1// Define what "high-risk" means in your organization (a Rule)
2await client.definitions.create({
3  name: 'High-risk contract',
4  definition_type: 'rule',
5  definition: 'A contract with liability exceeding $1M OR containing a termination amendment',
6});
7
8// Define customer tiers (a Term)
9await client.definitions.create({
10  name: 'Enterprise customer',
11  definition_type: 'term',
12  definition: 'A customer with annual contract value over $100K',
13});
14
15// Define a metric calculation
16await client.definitions.create({
17  name: 'Monthly Recurring Revenue',
18  definition_type: 'metric',
19  definition: 'Sum of all active monthly subscription values',
20});
21
22console.log('Logic definitions configured');

Now when you ask "which contracts are high-risk?", the agent knows exactly what "high-risk" means—no guessing, no keyword matching.

Logic definitions can be scoped to the entire workspace (available to all agents) or to specific datastores. See the Logic guide for more details.

Step 6: Ask a Question

Query your agent and get answers you can use:

javascript
1const response = await client.chat.query({
2  agent_id: agent.id,
3  message: 'Which contracts are high-risk?',
4});
5
6console.log('Answer:', response.content);
7console.log('Citations:', response.citations);

Example Response

json
1{
2  "content": "Based on your high-risk criteria (liability > $1M or termination amendment), I found 2 high-risk contracts:\n\n1. **Acme Corp Agreement** - Liability cap of $2.1M [1]\n2. **Beta Inc Contract** - Contains termination amendment in Section 12 [2]\n\nThe remaining 3 contracts in your datastore do not meet the high-risk threshold.",
3  "citations": [
4    {
5      "id": 1,
6      "document_name": "Acme Corp Agreement",
7      "page_number": 8,
8      "excerpt": "Total liability under this agreement shall not exceed $2,100,000..."
9    },
10    {
11      "id": 2,
12      "document_name": "Beta Inc Contract",
13      "page_number": 12,
14      "excerpt": "Either party may terminate this agreement with 30 days notice..."
15    }
16  ]
17}

Notice how the response applies your business rules, not just keyword matching. That's the difference between retrieval and reasoning.

Complete Example

Here's the complete code:

javascript
1import { Orka } from '@orka/sdk';
2import fs from 'fs';
3
4const client = new Orka({
5  apiKey: process.env.ORKA_API_KEY,
6});
7
8async function main() {
9  // 1. Create agent
10  const agent = await client.agents.create({
11    name: 'Contract Analyst',
12    system_prompt: 'You are a contract analyst. Apply business rules when answering questions. Cite your sources.',
13  });
14
15  // 2. Create datastore
16  const datastore = await client.datastores.create({
17    name: 'Contracts',
18  });
19
20  // 3. Upload document
21  const document = await client.documents.upload({
22    datastore_id: datastore.id,
23    file: fs.createReadStream('./contract.pdf'),
24  });
25
26  // 4. Wait for processing
27  await waitForProcessing(document.id);
28
29  // 5. Connect agent to datastore
30  await client.agents.connectDatastore({
31    agent_id: agent.id,
32    datastore_id: datastore.id,
33  });
34
35  // 6. Add logic definitions
36  await client.definitions.create({
37    name: 'High-risk contract',
38    definition_type: 'rule',
39    definition: 'Liability > $1M OR termination amendment',
40  });
41
42  // 7. Ask a question
43  const response = await client.chat.query({
44    agent_id: agent.id,
45    message: 'Which contracts are high-risk?',
46  });
47
48  console.log(response.content);
49}
50
51main();

Next Steps

Now that you've built a reasoning agent, explore these resources: