Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/5unnykum4r/grip-ai/llms.txt

Use this file to discover all available pages before exploring further.

Agent profiles let you configure specialized agents for different tasks. Each profile can override the default model, restrict available tools, and use a custom system prompt.

​
Profile Configuration

Profiles are defined in ~/.grip/config.json under the agents.profiles section: 
{
  "agents": {
    "profiles": {
      "researcher": {
        "model": "openrouter/google/gemini-flash-2.0",
        "temperature": 0.9,
        "max_tokens": 4096,
        "tools_allowed": ["web_search", "web_fetch", "read_file", "write_file"],
        "system_prompt_file": "agents/researcher.md"
      },
      "coder": {
        "model": "anthropic/claude-sonnet-4",
        "temperature": 0.3,
        "tools_denied": ["web_search", "send_email"],
        "system_prompt_file": "agents/coder.md"
      },
      "safe-assistant": {
        "tools_allowed": ["read_file", "web_search"],
        "tools_denied": ["exec", "shell", "delete_file"]
      }
    }
  }
}

​
Profile Schema

From grip/config/schema.py:369: 
class AgentProfile(BaseModel):
    """Named agent profile with its own model, tool subset, and system prompt.
    
    Profiles let you configure specialized agents (e.g. a "researcher" that
    uses a cheaper model with only web tools, or a "coder" with shell access).
    Fields left empty inherit from agents.defaults at runtime.
    """
    
    model: str = ""
    max_tokens: int = 0
    temperature: float = -1.0
    max_tool_iterations: int = 0
    tools_allowed: list[str] = Field(
        default_factory=list,
        description="Tool names this profile can use. Empty = all tools.",
    )
    tools_denied: list[str] = Field(
        default_factory=list,
        description="Tool names explicitly blocked for this profile.",
    )
    system_prompt_file: str = Field(
        default="",
        description="Workspace-relative path to a custom identity file (e.g. 'agents/researcher.md').",
    )

​
Tool Access Control

​
Allowlist Mode

Use tools_allowed to restrict the agent to only specific tools: 
{
  "readonly-analyst": {
    "tools_allowed": [
      "read_file",
      "list_directory",
      "web_search",
      "web_fetch"
    ]
  }
}
When tools_allowed is set, the agent can only use those tools. All other tools are blocked, including built-in tools like write_file or exec.

​
Denylist Mode

Use tools_denied to block specific dangerous tools while allowing everything else: 
{
  "safe-coder": {
    "tools_denied": [
      "exec",
      "shell",
      "delete_file",
      "delete_directory"
    ]
  }
}

​
Combined Mode

You can combine both for fine-grained control: 
{
  "web-scraper": {
    "tools_allowed": [
      "web_search",
      "web_fetch",
      "read_file",
      "write_file",
      "exec"
    ],
    "tools_denied": ["exec"]
  }
}
When both are set, tools_denied takes precedence. In the example above, exec is blocked even though it appears in tools_allowed.

​
Custom System Prompts

Create a custom identity file in your workspace to specialize agent behavior: 
mkdir -p ~/.grip/workspace/agents
cat > ~/.grip/workspace/agents/researcher.md << 'EOF'
# Research Assistant

You are a specialized research agent focused on gathering and synthesizing information from web sources.

## Principles

- Always verify information from multiple sources
- Cite sources with URLs
- Distinguish between facts and opinions
- Flag outdated information (>1 year old)
- Use academic and authoritative sources when possible

## Workflow

1. Break down research questions into searchable queries
2. Search using web_search with targeted keywords
3. Fetch and analyze top 3-5 results with web_fetch
4. Synthesize findings into a structured summary
5. Include a "Sources" section with all URLs referenced

## Output Format

Always structure research findings as:

**Summary**: 2-3 sentence overview

**Key Findings**:
- Finding 1 (Source: URL)
- Finding 2 (Source: URL)

**Details**: Expanded context and analysis

**Sources**: Full list of URLs consulted
EOF
Then reference it in your profile: 
{
  "researcher": {
    "system_prompt_file": "agents/researcher.md"
  }
}
System prompt files are workspace-relative paths. Use agents/name.md for organization, or store directly as researcher.md in the workspace root.

​
Inheritance from Defaults

Profile fields left empty inherit from agents.defaults: 
{
  "agents": {
    "defaults": {
      "model": "openrouter/anthropic/claude-sonnet-4",
      "max_tokens": 8192,
      "temperature": 0.7
    },
    "profiles": {
      "fast-coder": {
        "temperature": 0.3
        // Inherits model and max_tokens from defaults
      }
    }
  }
}

​
Using Profiles

Profiles are activated through the API or gateway: 
# Via REST API
curl -X POST http://localhost:18800/api/v1/agent/run \
  -H "Authorization: Bearer $GRIP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Research quantum computing trends",
    "profile": "researcher"
  }'

# Via Python SDK
from grip import GripClient

client = GripClient()
result = await client.run(
    "Research quantum computing trends",
    profile="researcher"
)

​
Example Profiles

​
Budget-Conscious Researcher

Uses a cheaper model with web-only tools: 
{
  "budget-researcher": {
    "model": "openrouter/google/gemini-flash-2.0",
    "max_tokens": 4096,
    "temperature": 0.8,
    "tools_allowed": ["web_search", "web_fetch", "read_file", "write_file"]
  }
}

​
Code Review Specialist

Focused on code analysis, blocks shell execution: 
{
  "code-reviewer": {
    "model": "anthropic/claude-sonnet-4",
    "temperature": 0.2,
    "tools_denied": ["exec", "shell", "delete_file", "web_search"],
    "system_prompt_file": "agents/code-reviewer.md"
  }
}

​
Data Analyst

Restricted to read-only operations with analysis tools: 
{
  "analyst": {
    "tools_allowed": [
      "read_file",
      "list_directory",
      "analyze_csv",
      "generate_chart",
      "web_search"
    ],
    "max_tool_iterations": 20,
    "system_prompt_file": "agents/analyst.md"
  }
}

​
Tool Names Reference

Common tool names for tools_allowed / tools_denied: Filesystem: read_file, write_file, edit_file, append_file, list_directory, delete_file, delete_directory Shell: exec, shell Web: web_search, web_fetch Communication: send_message, send_email Orchestration: spawn_agent, send_to_agent Finance: get_stock_price, get_crypto_price, analyze_portfolio Code: analyze_code, review_code, generate_docs Data: transform_csv, generate_chart, analyze_dataset
To see all available tools, run grip tools list or check ~/.grip/workspace/TOOLS.md after initialization.

​
Best Practices

  1. Name profiles descriptively: Use names like web-researcher or safe-coder that clearly indicate purpose
  2. Start restrictive: Begin with tools_allowed for security-critical profiles, then add tools as needed
  3. Match model to task:
    • Use cheaper models (Gemini Flash, GPT-4o-mini) for simple research or data lookup
    • Use premium models (Claude Opus, GPT-4) for complex reasoning or code generation
  4. Custom prompts for specialization: Define workflows, output formats, and quality standards in system_prompt_file
  5. Test tool restrictions: Verify that denied tools are actually blocked before deploying profiles
  6. Document profiles: Add comments in config.json explaining each profile’s purpose

Build docs developers (and LLMs) love

Get started for freeTalk to us