Skip to content
Alquimia Alquimia Alquimia

Quickstart

This guide runs a single agent locally using alquimia-core directly — no runtime service required.

What you’ll build

Section titled “What you’ll build”

A simple assistant that answers questions using an OpenAI-compatible LLM, with a one-shot evaluation strategy (no tools).

  1. Create the agent registry

    Terminal window
    alquimia registry create --name my-agents --namespace local

    This creates a local TinyDB-backed agentspace at $ALQUIMIA_REGISTRY_DIR.

  2. Write the agent configuration

    Save this as my-agent.json:

    my-agent.json
    {
      "assistant_id": "my-first-agent",
      "nickname": "Helper",
      "description": "A simple question-answering assistant.",
      "response": {
        "provider_id": "alquimia",
        "config": {
          "provider_id": "generative",
          "connector": {
            "provider_id": "openai",
            "model": "gpt-4o-mini",
            "api_key": { "$secretRef": "OPENAI_API_KEY" }
          }
        },
        "profile": {
          "system_prompt": "You are a helpful assistant. Answer questions clearly and concisely.",
          "evaluation_strategy": {
            "evaluation_strategy_id": "one-shoot"
          },
          "persistence_strategy": "INCREMENTAL"
        }
      }
    }

  3. Register the secret

    Terminal window
    export OPENAI_API_KEY=sk-...
    alquimia registry secrets add \
      --key OPENAI_API_KEY \
      --scope global \
      --agentspace-id default

  4. Add the agent to the registry

    Terminal window
    alquimia registry agents add --file my-agent.json --agentspace-id default

  5. Chat with the agent

    Terminal window
    alquimia local chat --assistant-id my-first-agent --agentspace-id default

    You’ll see an interactive prompt:

    You: What is the capital of France?
    Assistant: The capital of France is Paris.
    You: exit

Run programmatically

Section titled “Run programmatically”

Use evaluate() directly in Python:

run_agent.py
import asyncio
from alquimia.core import evaluate, get_assistant_config, get_local_session
from alquimia.core.assistant import AssistantInferenceController
from alquimia.core.base import CommonAttributes
from alquimia.core.command import AssistantInference
from alquimia.core.observability import setup_observability
from alquimia.registry.registry import AlquimiaRegistry


# Enable OTEL metrics — call once at startup before any evaluate() calls.
# Reads OTEL_COLLECTOR_ENDPOINT from the environment. No-op if not set.
setup_observability()


async def main():
    registry = AlquimiaRegistry()
    registry.load({"agentspace_id": "default"})


    config = get_assistant_config(registry, "my-first-agent")
    conversation = get_local_session()


    controller = AssistantInferenceController(
        context_metadata=CommonAttributes(
            assistant_id="my-first-agent",
            agentspace_id="default",
            user_id="user-1",
            session_id=conversation.session_id,
        )
    )


    command = AssistantInference(
        query="What is the capital of France?",
        conversation=conversation,
        parameters=config,
    )


    response = await evaluate(controller, command, registry)
    print(response.result.content)


asyncio.run(main())

Expected output:

The capital of France is Paris.

Next steps

Section titled “Next steps”

Source

Section titled “Source”