Agents

What is an Agent?

In OpenCognit, an agent is an AI worker with a defined role, a connected LLM provider and a specific skill set. Agents work autonomously on assigned tasks and communicate with the board via comments and live chat.

Agent Status

Status	Description
`idle`	Waiting for new tasks
`running`	Currently executing a heartbeat cycle
`paused`	Manually paused — no heartbeat
`error`	Error in the last cycle
`terminated`	Permanently deactivated

Creating Agents

Navigate to Agents

Open your company dashboard and click Agents → Add Agent.

Define basic data

Field	Description	Example
`name`	Display name	`Jane Smith`
`rolle`	Short role description	`Senior Frontend Developer`
`titel`	Job title	`Lead Engineer`
`reportsTo`	Manager agent (optional)	CEO Agent ID

Connect LLM provider

Choose the verbindungsTyp and enter the corresponding configuration. See Adapter Overview below.

Assign skills

Skills are tags that determine which tasks get assigned to this agent. Examples: react, typescript, devops, research, writing.

Enable Heartbeat (optional)

Enable zyklusAktiv for autonomous operation. Set zyklusIntervallSek (default: 300 seconds = 5 minutes).

Adapter Overview

Claude API

Direct connection to Anthropic Claude API. Great for complex reasoning tasks.

{
  "verbindungsTyp": "claude",
  "verbindungsConfig": {
    "model": "claude-opus-4-6",
    "maxTokens": 8096
  }
}

Claude Code CLI

Uses Claude Code CLI with session persistence. The agent can read, write files and execute commands — ideal for development tasks.

{
  "verbindungsTyp": "claude-code",
  "verbindungsConfig": {
    "workDir": "/home/user/my-project",
    "sessionPrefix": "opencognit-dev"
  }
}

The claude-code adapter runs inside workDir. This path must be outside the OpenCognit installation directory. See Agent Workspaces.

Gemini CLI

Uses Google Gemini CLI with your Google Account (Gemini Advanced / Google One AI Premium). No API key needed.

{
  "verbindungsTyp": "gemini-cli",
  "verbindungsConfig": {
    "model": "gemini-2.5-pro"
  }
}

Install: npm install -g @google/gemini-cli then gemini auth login. Shown in Settings only when installed.

Codex CLI

Uses OpenAI Codex CLI with your ChatGPT account (Plus/Pro). No API key needed.

{
  "verbindungsTyp": "codex-cli",
  "verbindungsConfig": {
    "model": "o4-mini",
    "approvalMode": "full-auto"
  }
}

Install: npm install -g @openai/codex then codex login. Shown in Settings only when installed.

OpenRouter

Access to 100+ LLM models through a single API. Flexible and cost-optimizable.

{
  "verbindungsTyp": "openrouter",
  "verbindungsConfig": {
    "model": "anthropic/claude-3.5-sonnet",
    "maxTokens": 4096
  }
}

Ollama (Local)

Local open-source models without cloud dependency. Privacy-friendly.

{
  "verbindungsTyp": "ollama",
  "verbindungsConfig": {
    "model": "llama3.2",
    "baseUrl": "http://localhost:11434"
  }
}

Bash Adapter

Executes shell commands. Useful for automation tasks.

{
  "verbindungsTyp": "bash",
  "verbindungsConfig": {
    "shell": "/bin/bash",
    "timeout": 300
  }
}

Dangerous commands are blocked: rm -rf, mkfs, dd, fdisk. Agents always run in an isolated workspace — never in the OpenCognit directory. Timeout: 5 minutes.

HTTP Adapter

Makes HTTP requests to external APIs. Ideal for integrations.

{
  "verbindungsTyp": "http",
  "verbindungsConfig": {
    "baseUrl": "https://api.example.com",
    "headers": {
      "Authorization": "Bearer my-token"
    }
  }
}

CEO Adapter

Special adapter for the orchestrator agent. Handles automatic task delegation based on company goals.

{
  "verbindungsTyp": "ceo"
}

The CEO adapter is set automatically when creating an orchestrator agent via the Onboarding Wizard.

Budget & Costs

Each agent tracks its token consumption. The budget system prevents uncontrolled costs.

Field	Description
`budgetMonatCent`	Monthly limit in cents (0 = no limit)
`verbrauchtMonatCent`	Costs consumed this month

When verbrauchtMonatCent >= budgetMonatCent, the heartbeat automatically stops for that agent.

SOUL.md — File-Based System Prompt

Instead of storing the system prompt in the database, you can use a SOUL.md file — a git-trackable Markdown file with template variables:

# Export current system prompt as SOUL.md
POST /api/experten/:id/export-soul

# Get SOUL.md content
GET /api/experten/:id/soul

# Update SOUL.md content
PUT /api/experten/:id/soul
Content-Type: application/json
{ "content": "# {{agent.name}}\n\nYour role: {{agent.role}}\n..." }

Available template variables: {{agent.name}}, {{agent.role}}, {{company.name}}, {{company.goal}}

SOUL.md takes priority over the systemPrompt field in the database. If the file is deleted, the system falls back to the database prompt automatically.

Agent API

GET /api/unternehmen/:id/experten
Authorization: Bearer <token>

POST /api/unternehmen/:id/experten
Content-Type: application/json

{
  "name": "Jane Smith",
  "rolle": "Senior Frontend Developer",
  "verbindungsTyp": "claude",
  "verbindungsConfig": { "model": "claude-sonnet-4-6" },
  "zyklusAktiv": true,
  "zyklusIntervallSek": 300,
  "budgetMonatCent": 5000
}

POST /api/experten/:id/pausieren
Authorization: Bearer <token>

POST /api/experten/:id/fortsetzen
Authorization: Bearer <token>

# Add skill
POST /api/experten/:id/skills
{ "skill": "react" }

# Remove skill
DELETE /api/experten/:id/skills/:skillId

On this page