Docs
Contents

Quick Start

This guide walks through creating a project, connecting models, uploading a document, and verifying knowledge-based answers in the agent workbench. You may use an existing organization and project. Page labels may differ by interface language and deployment.

Prerequisites

Quick Start: workflow diagram, not a runtime screenshot

Workflow diagram, not a runtime screenshot.

View the flow diagram in full size

1. Create or select a project

  1. Sign in to the target console, create or select an organization, and create or select a project. Record its actual project ID and region for subsequent requests.

  2. The project root opens the platform registration page at /overview/platforms. The separate /get-started project guide offers platform and server-side integration options.

  3. To call a client SDK from a browser application, register its actual domain on the project's platform page. Browser platform registration is not required for the server-side check in this guide.

Platform selection in the project guide

Figure: Project guide in a 2.12.0 environment. Available options depend on the deployment.

2. Configure models

  1. Open Models in the project and add a model provider. You can select the Alibaba Cloud Bailian (DashScope) preset or another provider supported by your deployment.

  2. Enter the provider credentials and connection settings, then enable a chat model and an embedding model that your account can use. A name appearing in the catalog does not guarantee that your account has access to it.

  3. The console generates the provider identifier; the connection name identifies the configuration. Record the actual configuration and select the models by name later.

3. Create a knowledge base and upload a document

  1. Open Knowledge Base, create a knowledge base with a name and optional description, and select an available embedding model. The console generates the knowledge base identifier. The embedding model cannot be changed after creation, and its dimension must match the model's actual output.

  2. Select a parser appropriate for the file. The default documentParser is vlm, which requires an available visionModel; for suitable plain text files you can select text. Parser capabilities and results differ.

  3. Open the knowledge base's Documents page and upload your test file. Ingestion after upload is enabled by default; if you turn it off, start ingestion from the document list. Wait until both the document and ingestion job are ready (ready) before searching.

  4. In Search, ask a question that the document can answer and compare the returned excerpts and sources with the original. To use a lexicon, create it on the project lexicons page and bind it in knowledge base settings. A lexicon is optional for this guide.

For example, upload a text file containing “The project can search internal documents through a knowledge base.”, then ask “How can the project search internal documents?”. Results depend on the actual model, document, and index state.

4. Verify the agent workbench

  1. Open the Agent Workbench. On first use, follow the page prompt to enable or initialize it.

  2. Select an available chat model and configure the prompt as needed. In the knowledge base selector, select the knowledge base you created, close the selector, and turn on Knowledge Search. The configuration saves automatically; wait for the saved indication.

  3. Send a question that the test document can answer, inspect the final response, and open any source shown to inspect its cited excerpts. To view the original document, return to the knowledge base search page. If the result is unexpected, first check the document state and retrieved excerpts.

Knowledge-base answer in the workbench

Figure: A Chinese question and answer using a synthetic document in a 2.12.0 test project.

Responses and citations depend on the model, retrieved results, and configuration. Reading workbench configuration verifies only the configuration endpoint, not an actual conversation.

5. Optional: verify server APIs

Create a project-level server API key on the project overview's API keys page. To check only the user list below, grant users.read; reading /v1/agent-runtime/project/config additionally requires agent-runtime.project. Grant only the scopes needed for your use, and never put a server key in browser code or commit it to a repository.

Set the actual endpoint and project ID in a local terminal. Interactive entry keeps the key out of common shell history; do not record your terminal input or print the key.

APPBASE_ENDPOINT="https://your-agentbase.example.com/v1"
APPBASE_PROJECT_ID="your-project-id"
read -r -s -p 'API key: ' APPBASE_API_KEY
printf '\n'

Check the public service version:

curl -sS -w '\nHTTP %{http_code}\n' "${APPBASE_ENDPOINT}/health/version"

List project users. The key is passed through standard input rather than expanded into curl arguments. An empty user list is a valid result.

(
  set +x
  set -o pipefail
  builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | \
    curl --disable --header @- -sS -w '\nHTTP %{http_code}\n' \
      -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
      "${APPBASE_ENDPOINT}/users"
)
unset APPBASE_API_KEY

These commands retain error response bodies. If a request fails, check the status code and response message, target environment, project ID, key expiry, and scopes. Do not share requests or logs containing the key.

Troubleshooting