How matheusbuniotto/goagent works
Project Type and Purpose
• This is a bare-bones Go implementation of an AI agent (“goAgent”) with a hexagonal (ports-and-adapters) architecture.
• The core goal is to let the agent invoke “tools” (file operations, interaction utilities, etc.) without relying on any SDK.
Key Components (to appear
a. Core Agent (agent/agent.go) – the domain logic.
b. Orchestrator (main.go) – bootstraps the agent, wires up tools, parses flags for model selection.
c. Ports (tools/definitions.go) – declare ToolDefinition and ToolFunction types (these are your “ports” interfaces).
d. Adapters (tools/adapter.go) – implement the ports by wrapping each ToolDefinition into a ToolAdapter.
e. Tool Implementations (tools/file_tools.go, tools/interaction_tools.go) – concrete logic for each tool, invoked by adapters.
f. External AI Providers – raw HTTP clients calling OpenAI or Gemini APIs.
g. (Omit tests, go.mod, README.md, .gitignore per instructions.)
Relationships and Data Flow
• main.go → constructs a list of ToolAdapters (adapters) that satisfy the Ports defined in definitions.go.
• main → instantiates the Agent, passing in the list of adapters.
• Agent receives a user prompt → consults an LLM (OpenAI/Gemini) → parses LLM response to find a tool invocation.
• Agent calls ToolAdapter.Execute(input) → adapter calls the underlying ToolFunction (the port implementation).
• ToolFunction may read/write files (via file_tools) or run interactions (via interaction_tools).
• Agent collects the result → possibly loops back to the LLM or returns final output to the user.
Architectural Patterns and Design Principles
• Hexagonal Architecture (Ports & Adapters)
• Clear separation of concerns:
• Ports (definitions.go) declare interfaces for tools
• Adapters (adapter.go) implement those interfaces
• Tool implementations contain business logic, isolated from agent orchestration
• Dependency inversion: the core Agent depends only on the Ports, not on concrete tool logic
Detail
• Exactly how definitions.go (Ports) sit alongside adapter.go (Adapters).
• Make it explicit that each ToolDefinition in definitions.go is a port interface, and ToolAdapter in adapter.go implements it.
• Fact that tools live in their own sub‐package, keeping the core agent independent of concrete implementations.