For AI Agents

Last updated: April 11, 2026

For AI Agents

This guide provides specific coding standards and architectural patterns for AI agents (like Gemini, Claude, or internal dLANDiscord agents) working in this Go codebase.

🧬 Coding Standards

  • Imports: Grouped and alphabetized. Standard library first, then local packages, then external dependencies.
  • Naming:
    • Exported: PascalCase (e.g., ChatSession, NewPlannerSession).
    • Unexported: camelCase (e.g., parseModelIdentifier, loadConfig).
    • Acronyms: Uppercase (e.g., URL, HTTP, API, SSE, LLM).
    • Short Vars: Standard Go (e.g., ctx, err, msg, req, resp).
  • JSON Tags: Use snake_case (e.g., json:"created_at").
  • Logging: Use bracketed prefixes (e.g., log.Printf("[INFO] Message")). Prefer the structured Logger interface in assistant/ for all agent-related logs.

🏗️ Architectural Patterns

1. ReAct & Planning

When implementing new agentic behavior, follow the ReAct (Reason + Act) pattern. Ensure your agent can decompose tasks into a plan tree and adapt that plan based on tool results.

2. Dependency Injection

Prefer passing dependencies via constructors or interfaces (e.g., interfaces.GetAssistant()) rather than using global variables where possible.

3. Concurrency Safety

The dLANDiscord backend is highly concurrent. Always use sync.Mutex or sync.RWMutex to protect shared state, especially in ChatSession or registries.

4. Error Handling

Never ignore errors. Wrap errors with context using fmt.Errorf("context: %w", err). For LLM tool calls, use the RepairJSON middleware to ensure reliability.

🛠️ How to Extend the System

Adding a New Tool

  1. Define: Create a new markdown file in assistant/prompts/tools/{agent}/.
  2. Implementation:
    • If a Shell Tool, add the script snippet directly into the markdown.
    • If a Go Tool, add the corresponding logic to assistant/assistant.go or a specialized module file.
  3. Registration: Ensure the tool is correctly indexed and available to the intended agents.

Adding a New Agent

  1. Persona: Create a new markdown file in assistant/prompts/agent/ with the agent's name, description, and core directives.
  2. Model Configuration: Define the Model: and FallBackModel: headers in the agent's markdown for dynamic model selection.
  3. Tooling: Specify the set of tools the agent is permitted to use.

⚠️ Important Gotchas

  • Zombie Contexts: Be aware of the ZombieParentRegistry when implementing asynchronous or background tasks to ensure results reach the user even if the session is rehydrated.
  • RBAC Enforcement: Always check the AllowedRoles for any new tool you create. Tools with missing or incorrect roles may be inaccessible.
  • Large Files: main.go and assistant.go are extremely large. Use targeted reading and search tools rather than reading the whole file.

For technical details on the framework, see Assistant Core.