Quickstart

This guide uses alquimia-core directly — no runtime service required. You will create a local agentspace, define a simple agent, and chat with it.

Prerequisites

Python 3.12 installed.
An API key for an OpenAI-compatible LLM provider.
The alquimia-core package installed. See Installation for options.

Run your first agent

Create an agentspace. An agentspace is a namespace that holds agent configurations, secrets, and parameters.
Terminal window
```
alquimia registry create --name default
```

Register your API key as a secret in the agentspace. Secrets are referenced by name in the agent spec, never embedded directly.

alquimia registry secrets add RESPONSE_PROVIDER_API_KEY --scope shared --required
alquimia registry secrets put RESPONSE_PROVIDER_API_KEY "$RESPONSE_PROVIDER_API_KEY"

Create an agent configuration that declares the agent’s identity, system prompt, model connector, and memory strategy.

{
  "assistant_id": "support-bot",
  "nickname": "Support Bot",
  "description": "Answers product support questions",
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "You are a helpful support assistant. Answer concisely.",
      "evaluation_strategy": { "evaluation_strategy_id": "one-shoot" },
      "persistence_strategy": "INCREMENTAL"
    },
    "config": {
      "provider_id": "openai",
      "params": {
        "model": "gpt-4o-mini",
        "temperature": 0.3,
        "api_key": { "$secretRef": "RESPONSE_PROVIDER_API_KEY" }
      }
    }
  }
}

Register the agent in the local registry.

alquimia registry agents add support-bot.json --namespace default

Start a conversation using the CLI and ask a question. The agent loads the spec, resolves the secret, calls the model, and returns an answer.
Terminal window
```
alquimia local chat default/support-bot
alquimia local exec default/support-bot "What can you help me with?"
```
As of alquimia-core 0.5.2, you can also run a specific OCI-tagged version without changing the workspace:
Terminal window
```
alquimia registry fetch --namespace default --tag v1.0.0
alquimia local exec default/support-bot:v1.0.0 "What can you help me with?"
```

What happens under the hood

The CLI loads the agent spec from the local registry.
The core engine resolves the secret reference to your API key.
The agent sends the conversation to the configured LLM.
The response is returned and the session is persisted.

Next steps

Agents & configuration — understand the agent spec.
Tools & integrations — connect APIs and other agents.
Docker Compose deployment — run the full platform stack.