Skip to content

Agent System

Built-in Agents

Gravity ships with five core agents, each exposing a structured descriptor defining name, description, write capability, and actions with parameters.

FileAgent (code_editor)

Primary file system operations agent. All actions support both absolute and workspace-relative paths.

  • read_file — Read entire file or specify line range
  • write_file — Create or overwrite file content
  • apply_diff — Surgical edits via unified diff format
  • list_directory — Directory listing with file metadata
  • search_in_files / grep — Content search with regex support
  • glob — Pattern-based file finding (e.g., **/*.cs)
  • delete — Remove files (requires Review/Assisted mode approval)
  • read_range — Read specific line range from large files

ShellAgent (terminal)

Command execution agent with specialized helpers for common development tasks.

  • run_command — Arbitrary shell command with timeout
  • dotnet — dotnet build|test|run|restore|publish with project detection
  • git — git status|diff|log|add|commit|push|pull
  • powershell — PowerShell scripts and cmdlets
  • where — Locate binary on PATH

KnowledgeAgent (knowledge)

Persistent knowledge base management for SOPs and learned patterns.

  • list — List all knowledge items
  • read — Read a knowledge item by key
  • add — Create new knowledge item (SOP) at runtime

Knowledge items stored as markdown in knowledge/ directory.

GravityAgent (gravity)

Meta-agent for system introspection and task planning.

  • about — System information and version
  • context — Project context dump for debugging
  • help — Available tools and usage
  • plan — Create task plan from natural language
  • propose — Create implementation plan
  • walkthrough — Generate walkthrough of changes

SearchAgent (search)

Web search and content extraction.

  • web — Wikipedia & LangSearch multi-source search
  • fetch / read_url — Deep page scraping, markdown conversion, link extraction

IAgent Interface

public interface IAgent
{
    Task ExecuteAsync(AgentRequest request, CancellationToken ct);
    AgentDescriptor Descriptor { get; }
}

All agents implement this interface. The ExecuteAsync method receives an AgentRequest containing the tool name, parameters, and context, and returns an AgentResult with success status, output, and any artifacts.

Agent Descriptors

Each agent exposes metadata via AgentDescriptor:

public class AgentDescriptor
{
    public string Name { get; set; }
    public string Description { get; set; }
    public bool CanWrite { get; set; }
    public List Actions { get; set; }
}

ActionMetadata includes name, description, JSON schema for parameters, and mutation flags (IsDestructive, RequiresApproval).

Reasoning Router

The ReasoningRouter resolves tool calls from the LLM to concrete IAgent implementations. It validates parameters against the action's JSON schema, enforces approval policies based on IsDestructive flags, and handles both built-in and dynamic/MCP agents uniformly.