Skip to main content

​
Agents

Agents are AI-powered coding assistants that execute tasks within AgentGate’s orchestration framework. AgentGate supports multiple agent drivers, each with different capabilities, billing models, and use cases.

​
What Are Agents

An agent is an AI system that can:
  • Read and write code: Understand codebases and make changes
  • Execute commands: Run tests, builds, and other shell commands
  • Use tools: Leverage MCP servers, browser automation, and custom tools
  • Iterate on feedback: Respond to verification failures and improve code
AgentGate abstracts agent interaction through drivers, allowing you to swap between different AI providers and billing models.

​
Available Drivers

Use your Claude Pro/Max subscriptionThe default driver that uses your Claude subscription for billing instead of API credits.
execution:
  agent:
    driver: claude-code-subscription
    maxTokens: 200000
Requirements:
  • Active Claude Pro or Max subscription
  • OAuth credentials at ~/.claude/.credentials.json
  • Claude CLI installed
Capabilities:
FeatureSupported
Session ResumeYes
Structured OutputYes
Tool RestrictionYes
Timeout ControlYes
StreamingYes
Cost TrackingNo (subscription)
This driver automatically excludes ANTHROPIC_API_KEY from the environment to ensure subscription billing is used.

​
Agent Specification

Configure agents in the execution.agent section of your TaskSpec: 
execution:
  agent:
    driver: claude-agent-sdk
    model: claude-sonnet-4-20250514
    maxTokens: 200000
    temperature: 0.7
    systemPrompt: |
      You are an expert TypeScript developer.
      Write clean, well-tested code.
      Follow the project's existing patterns.
    tools:
      - name: bash
        enabled: true
      - name: file_system
        enabled: true
      - name: browser
        enabled: false
    mcpServers:
      filesystem:
        command: "npx"
        args: ["-y", "@anthropic/mcp-server-filesystem"]
        env:
          ALLOWED_PATHS: "/workspace"
    capabilities:
      fileSystem: true
      network: true
      shell: true
      browser: false

​
Configuration Options

OptionTypeDefaultDescription
driverstringclaude-code-subscriptionAgent driver to use
modelstringvariesAI model (e.g., claude-sonnet-4-20250514)
maxTokensnumber200000Maximum context tokens
temperaturenumber0.7Generation temperature (0-2)
systemPromptstring-Custom system prompt
toolsToolSpec[]-Tool configurations
mcpServersobject-MCP server configurations
capabilitiesobject-Capability flags

​
Agent Capabilities

Capabilities define what actions an agent can perform: 
capabilities:
  fileSystem: true   # Read/write files
  network: true      # Make HTTP requests
  shell: true        # Execute shell commands
  browser: false     # Browser automation

​
Standard Capabilities

AgentGate defines these standard capability names:
CapabilityDescription
networkNetwork access for HTTP requests
filesystemRead and write files
shellExecute shell commands
browserBrowser automation (Playwright, etc.)
dockerDocker container operations
databaseDatabase access
code-executionExecute code in various languages
tool-useUse MCP tools and servers

​
Capability Matching

When a task has capability requirements, AgentGate matches them against available agents: 
# In TaskSpec
spec:
  goal:
    prompt: "Scrape data from website"
    requirements:
      requiredCapabilities:
        - name: browser
          required: true
        - name: network
          required: true
      preferredCapabilities:
        - name: shell
          required: false

​
Tools and MCP Servers

​
Tool Configuration

Enable or disable specific tools: 
tools:
  - name: bash
    enabled: true
    config:
      allowedCommands: ["npm", "git", "node"]

  - name: file_system
    enabled: true
    config:
      allowedPaths: ["/workspace"]

  - name: browser
    enabled: false  # Disable browser tool

​
MCP Server Configuration

Configure Model Context Protocol servers: 
mcpServers:
  filesystem:
    command: "npx"
    args: ["-y", "@anthropic/mcp-server-filesystem"]
    env:
      ALLOWED_PATHS: "/workspace"

  github:
    command: "npx"
    args: ["-y", "@anthropic/mcp-server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"

  postgres:
    command: "npx"
    args: ["-y", "@anthropic/mcp-server-postgres"]
    env:
      DATABASE_URL: "${DATABASE_URL}"

​
Agent Request Flow

When AgentGate executes a task, it creates an AgentRequest: 
interface AgentRequest {
  workspacePath: string;     // Path to code workspace
  taskPrompt: string;        // What to accomplish
  gatePlanSummary: string;   // Gates that must pass
  constraints: {
    allowedTools: string[];
    disallowedTools: string[];
    maxTurns: number;
    permissionMode: 'plan' | 'acceptEdits' | 'bypassPermissions';
    additionalSystemPrompt: string | null;
  };
  priorFeedback: string | null;  // Feedback from failed gates
  timeoutMs: number;
  sessionId: string | null;      // For session resume
}

​
Agent Result

Agents return structured results: 
interface AgentResult {
  success: boolean;
  exitCode: number;
  stdout: string;
  stderr: string;
  structuredOutput: {
    type?: string;
    result: string;
    total_cost_usd?: number;
    usage?: {
      input_tokens: number;
      output_tokens: number;
    };
  } | null;
  sessionId: string | null;
  tokensUsed: {
    input: number;
    output: number;
    cacheRead?: number;
    cacheCreation?: number;
  } | null;
  durationMs: number;
  totalCostUsd?: number;
  model?: string;
}

​
Constraints

Control agent behavior with constraints: 
constraints:
  # Tools the agent CAN use
  allowedTools:
    - bash
    - file_system
    - read
    - write
    - edit

  # Tools the agent CANNOT use
  disallowedTools:
    - browser
    - web_search

  # Maximum conversation turns
  maxTurns: 50

  # Permission mode
  permissionMode: acceptEdits  # plan | acceptEdits | bypassPermissions

  # Additional system prompt
  additionalSystemPrompt: |
    Focus on security best practices.
    Do not commit secrets to version control.

​
Permission Modes

ModeDescriptionUse Case
planAgent plans but asks before executingHigh-risk changes
acceptEditsAgent can edit files automaticallyNormal development
bypassPermissionsFull autonomyTrusted automation

​
Session Management

Agents can resume sessions for multi-iteration tasks: 
# AgentGate automatically manages sessions
convergence:
  strategy: ralph
  config:
    promptHotReload: true  # Allow prompt updates mid-session

​
Session Resume

When a gate fails and triggers iteration:
  1. AgentGate captures the sessionId from the result
  2. Next iteration passes sessionId in the request
  3. Agent resumes with full conversation context
  4. Feedback from failed gates is appended
Not all drivers support session resume. Check supportsSessionResume in capabilities.

​
Billing Methods

​
Subscription Billing

The claude-code-subscription driver uses your Claude Pro/Max subscription:
  • No per-token charges
  • Rate limits based on subscription tier
  • Requires OAuth authentication

​
API Billing

The claude-code-api and claude-agent-sdk drivers use API credits:
  • Pay-per-token pricing
  • Higher rate limits available
  • Cost tracked in totalCostUsd
# Track costs in your TaskSpec
convergence:
  limits:
    maxCost: "$50"  # Stop if cost exceeds $50

​
Driver Selection

AgentGate uses a driver registry to select agents: 
// Drivers are registered at startup
driverRegistry.register(new ClaudeCodeSubscriptionDriver());
driverRegistry.register(new ClaudeAgentSDKDriver());

// Get specific driver
const driver = driverRegistry.get('claude-code-subscription');

// Get default driver
const defaultDriver = driverRegistry.getDefault();

​
Automatic Selection

If you don’t specify a driver, AgentGate selects based on availability:
  1. Check if claude-code-subscription is available (subscription valid)
  2. Fall back to claude-code-api if API key is set
  3. Try other registered drivers

​
Best Practices

1

Choose the Right Driver

  • claude-code-subscription: Best for regular development work
  • claude-agent-sdk: Best for complex orchestration
  • claude-code-api: Best when you need cost tracking
2

Set Appropriate Limits

execution:
  agent:
    maxTokens: 200000  # Match your model's context

convergence:
  limits:
    maxCost: "$100"    # Prevent runaway costs
    maxTokens: 1000000 # Total token budget
3

Use Constraints Wisely

  • Disable unused tools to reduce context
  • Set maxTurns to prevent infinite loops
  • Use additionalSystemPrompt for task-specific guidance
4

Leverage Session Resume

  • Use ralph strategy for session continuity
  • Provide context pointers for large codebases
  • Enable promptHotReload for iterative refinement

​
Troubleshooting

Check that:
  1. You have an active Claude Pro/Max subscription
  2. OAuth credentials exist at ~/.claude/.credentials.json
  3. The credentials are not expired
# Verify subscription status
claude auth status
Verify your API key:
# Check if key is set
echo $ANTHROPIC_API_KEY

# Test API access
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":1,"messages":[{"role":"user","content":"Hi"}]}'
Increase timeout in your TaskSpec:
execution:
  sandbox:
    resources:
      timeout: "2h"  # Increase from default
Check tool configuration:
tools:
  - name: browser
    enabled: true  # Ensure it's enabled

capabilities:
  browser: true    # And capability is set

TaskSpec

Configure agents within TaskSpec

Execution

Workspace and sandbox configuration

Convergence

Iteration and session management

Gates

Verification checkpoints for agents