Genebank AI Agent

The Genebank AI Agent provides an intelligent assistant capable of querying your collection, generating professional accession narratives, and helping with complex data filtering.

The agent runs as a separate service that bridges the GGCE frontend with a large language model (LLM) and the GGCE API. The agent is deployed as a service in ggce.yml.

Once correctly configured, the Genebank AI Agent menu will appear in the GGCE navigation menu for administrators and users in the AI group.

Use the installer

Navigate to Deploy GGCE with Docker and enable the option GGCE AI agent. This will prepare the updated ggce.yml file.

Environment Variables

The Agent container uses the following environment variables:

Variable	Description	Default
FRONTEND_URL	The public URL of your GGCE instance. This is used for CORS and link generation.	Required
API_URL	The base URL for the GGCE API. In most Docker deployments, use the internal network URL: http://ggce-api:8080/backend.	Required
PORT	The port on which the agent server listens.	3033
CONFIG_DIR	Directory containing LLM configuration and authentication.	/app/config
WORK_DIR	Working directory for project context and custom agent personas.	/app/work
LOG_LEVEL	Logging verbosity (e.g., info, debug, error).	info
TOKEN_INPUT_BUDGET	Default input token budget for each user.	50000
TOKEN_OUTPUT_BUDGET	Default output token budget.	5000
TOKEN_RESET_INTERVAL_MINUTES	Interval for resetting token counts.	5

Connecting to a large language model

The agent requires a configuration directory (CONFIG_DIR) to connect to an LLM provider. Inside the configuration directory, you must provide:

• settings.json: General agent settings, including the default provider and model name. See the Pi documentation for details.
• models.json: A registry of available models and their configuration. See supported models.
• auth.json: API keys and authentication credentials for your chosen LLM provider. See provider authentication.

settings.json

{
"defaultProvider": "ollama-cloud",
"defaultModel": "gemma4:31b",
"hideThinkingBlock": false,
"defaultThinkingLevel": "medium",
"images": {
  "blockImages": true
},
"enableInstallTelemetry": false
}

models.json

{
"providers": {
  "ollama": {
    "baseUrl": "http://<YOUR_LOCAL_OLLAMA_SERVER>:11434/v1",
    "api": "openai-completions",
    "apiKey": "ollama",
    "models": [
      {
        "id": "gemma4:latest",
        "reasoning": true, 
        "contextWindow": 120000,
        "maxTokens": 8000
      },
      {
        "id": "qwen3.5:latest",
        "reasoning": true,
        "contextWindow": 120000,
        "maxTokens": 8000
      }
    ]
  },
  "ollama-cloud": {
    "baseUrl": "https://ollama.com/v1",
    "api": "openai-completions",
    "apiKey": "ollama-cloud",
    "models": [
      {
        "id": "gemma4:31b",
        "reasoning": true,
        "details": {
          "parent_model": "gemma4:31b",
          "format": "",
          "family": "gemma4",
          "families": null,
          "parameter_size": "32682372656",
          "quantization_level": "BF16"
        },
        "model_info": {
          "gemma4.context_length": 262144,
          "gemma4.embedding_length": 5376,
          "general.architecture": "gemma4",
          "general.parameter_count": 32682372656
        },
        "capabilities": [
          "completion",
          "thinking",
          "tools",
          "vision"
        ],
        "modified_at": "2026-04-02T09:00:00-08:00"
      }
    ]
  }
}
}

auth.json

{
"ollama-cloud": {
  "type": "api_key",
  "key": "abcd.efgh"
}
}

Amazon Bedrock

Amazon Bedrock models are enabled by adding login credentials to the agent's environment variables:

  agent:
    # ... existing config ...
    environment:
      ## ... other variables
      AWS_ACCESS_KEY_ID: AKIA...
      AWS_SECRET_ACCESS_KEY: ...
      AWS_REGION: eu-central-1

and updating settings.json:

{
  "defaultProvider": "amazon-bedrock",
  "defaultModel": "eu.anthropic.claude-haiku-4-5-20251001-v1:0",
  // ... other options
}

Updating models.json is not required.

Customizing the agent

The WORK_DIR volume allows you to customize the agent's behavior, override the global persona, and add specialized skills:

• AGENTS.md: Deployment-specific instructions that override the global identity.
• .pi/skills/: Additional skill definitions. See Pi documentation for instructions.

Enabling AI Features for Users

By default, the agent is available to GGCE Administrators. To grant a user access to the AI features:

1. Go to Admin tools > User groups.
2. Create a group with the tag AI.
3. Go to Admin tools > Users.
4. Select the user you wish to authorize.
5. Add the user to the AI user group. The membership in the group takes effect on the next login.

Token Budgets

Environment variables TOKEN_INPUT_BUDGET and TOKEN_OUTPUT_BUDGET control how many tokens are available to each user within the TOKEN_RESET_INTERVAL_MINUTES interval.