Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quick Start: C

Embed Archia directly in your C/C++ application for maximum performance.

Prerequisites

  • Compiler: gcc, clang, or MSVC
  • API Key: LLM API keys or an open-source LLM

Your First AI Agent in C

Step 1: Create hello.c

#include <archia.h>
#include <stdio.h>

int main() {
    // Create Archia engine
    struct Engine *engine = archia_new();
    if (!engine) {
        fprintf(stderr, "Failed to create engine\n");
        return 1;
    }
    
    // Create a chat session
    size_t chat_id = archia_new_chat(
        engine,
        "You are a helpful assistant",  // System prompt
        NULL,                           // No MCP servers
        0                               // No user data
    );
    
    archia_send(
        engine,
        chat_id,
        "claude-haiku-4-5-20251001",      // Model
        "Hello! Tell me a fun fact."    // Message
    );
    archia_wait_on(engine, chat_id);    // Blocks thread until chat has a full response available. 
    
    // Get and print response
    size_t msg_count = archia_chat_len(engine, chat_id);
    const char* response = archia_chat_message(engine, chat_id, msg_count - 1);
    
    printf("Assistant: %s\n", response);
    
    // Cleanup
    archia_free(engine);
    return 0;
}

Step 2: Compile

# Linux
gcc -o hello hello.c -larchia 

# macOS  
clang -o hello hello.c -larchia

# Windows (MSVC)
cl hello.c archia.lib

Step 3: Run

export ANTHROPIC_API_KEY="sk-ant-..."  # Or OPENAI_API_KEY
./hello

# Output:
Assistant: "Here is a fun fact: Octopuses have three hearts! Two pump blood to the gills, 
while the third pumps blood to the rest of the body. Interestingly, the main heart 
stops beating when they swim, which is why they prefer crawling."

Interactive Chat Example

Build a complete interactive chat application:

// chat.c - Interactive chat program
#include "archia.h"
#include <stddef.h>
#include <stdio.h>
#include <string.h>

#define MAX_INPUT 1024

int main(int argc, char **argv) {
    struct Engine *engine = archia_new();
    if (!engine) {
        fprintf(stderr, "failed to initialize archia\n");
        return 1;
    }
    size_t chat_id = archia_new_chat(engine, "You are a knowledgeable friendly AI assistant. Be concise and helpful", NULL,  0, NULL);

    printf("Chat initialized. Type 'quit' to exit.\n");
    printf("You can ask me anything!\n\n");

    char input[MAX_INPUT];

    while (1) {
        printf("You: ");
        fflush(stdout);

        // Get user input
        if (!fgets(input, MAX_INPUT, stdin)) {
            break;
        }

        // Check for quit
        if (strncmp(input, "quit\n", MAX_INPUT) == 0) {
            break;
        }

        archia_send(engine, chat_id, "claude-sonnet-4-20250514", input);
        archia_wait_on(engine, chat_id);

        size_t len = archia_chat_len(engine, chat_id);
        const char* response = archia_chat_message(engine, chat_id, len - 1);
        printf("\nAssistant: %s\n\n", response);
        fflush(stdout);
    }

    printf("Goodbye!\n");
    archia_free(engine);
    return 0;
}

Compile and run:

export ANTHROPIC_API_KEY="sk-ant-..."  # Or OPENAI_API_KEY
clang -o chat chat.c -larchia
./chat

Using MCP Servers

Add tools and data access to your C application:

// calculator.c - Agent with access to a real calculator
#include "archia.h"
#include <stdio.h>

int main(int argc, char **argv) {
    struct Engine *engine = archia_new();

    size_t mcp_calc_id;
    archia_new_mcp_local_shell(&mcp_calc_id, engine, "calculator", 0);
    archia_wait_any(engine);

    size_t chat_id = archia_new_chat(engine, NULL, &mcp_calc_id, 1, NULL);
    archia_send(engine, chat_id, "claude-sonnet-4-20250514", "What is the sum of 83 and 73?");
    archia_wait_on(engine, chat_id);

    size_t len = archia_chat_len(engine, chat_id);
    for (size_t i = 0; i < len; ++i) {
        printf("%s\n", archia_chat_message(engine, chat_id, i));
    }

    archia_free(engine);
    return 0;
}

// everything.c - Agent using MCPs that are fed an environment on start.
#include "archia.h"
#include <stdio.h>

int main(int argc, char **argv) {
    struct Engine *engine = archia_new();

    size_t mcp_calc_id;
    char *args[] = { "-y", "@modelcontextprotocol/server-everything@latest" };
    struct Env env[] = {
        {.key = "EXAMPLE_ALPHA", .value = "some_example_value" },
        {.key = "EXAMPLE_BETA", .value = "other_example_value" }
    }; 
    archia_new_mcp_local(&mcp_calc_id, engine, "npx", args, 2, env, 2, 0);
    archia_wait_any(engine);

    size_t chat_id = archia_new_chat(engine, NULL, &mcp_calc_id, 1, NULL);
    archia_send(engine, chat_id, "claude-sonnet-4-20250514", "List the environment variables you have in a markdown file.");
    archia_wait_on(engine, chat_id);

    size_t len = archia_chat_len(engine, chat_id);
    for (size_t i = 0; i < len; ++i) {
        printf("%s\n", archia_chat_message(engine, chat_id, i));
    }

    archia_free(engine);
    return 0;
}

Performance Tips

  1. Reuse the Engine: Create once, use for all chats
  2. Batch Operations: Send multiple messages before waiting
  3. Use Appropriate Models: Haiku for speed, Sonnet for quality
  4. Stream Responses: Use streaming API for long outputs
  5. Cache Common Queries: Store frequently asked questions

Troubleshooting

Linker Errors

# undefined reference to `archia_new'
# Add -larchia to your compile command
gcc program.c -larchia

# Library not found
# Add library path
gcc program.c -L/usr/local/lib -larchia

# Update library cache (Linux)
sudo ldconfig

Runtime Errors

# Library not found at runtime
# Linux:
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

# macOS:
export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH

# Windows:
# Add C:\archia\bin to PATH

API Key Issues

// Set in code
setenv("ANTHROPIC_API_KEY", "sk-ant-...", 1);

// Or use config file
archia_set_config_file(engine, "~/.archia/config.toml");

Next Steps