Octopus_Agents Table

Purpose of the Table

Before an Octopus agent can process a conversation, the framework looks up its configuration in Octopus_Agents. This table is the source of truth for agent identity and capability. A missing or inactive agent record means no conversations can start for that agent.

The table is read-heavy at runtime (agent config is cached in memory after the first load) and write-light (agents are registered and updated infrequently compared to episode writes).

Column Reference

Config JSON Schema

The Config column holds a JSON object that controls how the agent calls the underlying LLM:

{
  "modelId": "gpt-4o",
  "temperature": 0.7,
  "maxTokens": 4096,
  "topP": 1.0,
  "frequencyPenalty": 0.0,
  "presencePenalty": 0.0,
  "contextWindowLimit": 32000,
  "memoryStrategyId": "sliding-window",
  "responseFormat": "text"
}

PluginRefs JSON Schema

The PluginRefs column is a JSON array of plugin identifiers. The Octopus framework resolves these identifiers to registered plugin implementations at agent initialization time:

["sql-server", "web-driver", "semantic-kernel", "mcp-brave-search"]

Only plugins in this list are available to the agent. If a plugin is listed but not registered in the plugin registry, initialization fails with a descriptive error.

Status Lifecycle

Common Queries

-- List all active agents for a tenant
SELECT AgentId, Name, Version, UpdatedAt
FROM Octopus_Agents
WHERE TenantId = @tenantId
  AND Status = 'Active'
ORDER BY Name;

-- Find agents using a specific plugin
SELECT AgentId, Name
FROM Octopus_Agents
WHERE TenantId = @tenantId
  AND JSON_QUERY(PluginRefs) LIKE '%sql-server%'
  AND Status = 'Active';

-- Get full agent config for runtime initialization
SELECT AgentId, Name, SystemPrompt, PluginRefs, Config, Version
FROM Octopus_Agents
WHERE TenantId = @tenantId
  AND AgentId = @agentId
  AND Status = 'Active';