Tools

Tools execute actions for the agent. Built-in tools provide connection calls, stores, reference lookup, and chat controls. Custom tools implement your product's calculations, API workflows, and data transformations.

amodal/tools/
└── create_ticket/
    ├── tool.ts         ← tool metadata and handler code
    ├── package.json    ← (optional) npm dependencies
    └── requirements.txt ← (optional) Python dependencies

Iteration Loop

Custom tool code is source-controlled in the agent repo. To change a tool, edit files under amodal/tools/, commit, push to the connected GitHub branch, and redeploy the agent.

Use the Platform API for the deploy loop:

curl "$AMODAL_API_BASE/api/deployments/redeploy" \
  -H "Authorization: Bearer $AMODAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"'"$AMODAL_AGENT_ID"'","branch":"main","environment":"production"}'
 
curl "$AMODAL_API_BASE/api/builds/$AMODAL_BUILD_ID/logs" \
  -H "Authorization: Bearer $AMODAL_API_KEY"

Build logs are the first place to look for TypeScript, dependency, manifest, and validation failures. Built-in platform tools are configured separately from custom tool code; use the platform-tools API only to enable or disable built-in tools.

Built-in Tools

Built-in tools appear in the agent's tool list when their prerequisites and the agent's resource scope allow them.

Web Tools

web_search and fetch_url give the agent grounded access to the public web. They're opt-in via a webTools block in amodal.json:

{
  "webTools": {
    "provider": "google",
    "apiKey": "env:GOOGLE_API_KEY"
  }
}

Both tools use a separate Google provider with Search and urlContext grounding, regardless of the main agent's model. google is the supported web-tool provider. Omit model to use the runtime's search default, or set a Gemini model that supports these features. A named agent must declare web_search and fetch_url in its tools.

web_search

web_search({query: "kubernetes 1.31 deprecations", max_results: 5})

Returns a synthesized answer (up to 2000 tokens) with cited source URLs. max_results defaults to 5, capped at 10. Include relevant dates, names, or error messages in the query.

fetch_url

fetch_url({url: "https://example.com/article", prompt: "Extract the API changes"})

Public URLs use Gemini's urlContext grounding to fetch and summarize the page. Private-network URLs (localhost, RFC1918, .local) automatically route through a local fetch path with Mozilla Readability extraction.

• Per-hostname rate limit: 10 requests / 60 seconds
• Local fetch: 10s timeout, 1MB body cap
• Falls back to local fetch if Gemini urlContext fails

Error handling

Provider errors are classified by HTTP status so the agent knows whether to retry:

Unexpected errors bubble as ToolExecutionError.

An End-to-End Example

This tool reads a support ticket and returns its status and recommended next action. It assumes a support-api connection.

The tool definition

amodal/tools/
└── summarize_ticket/
    └── tool.ts

export default {
  id: 'summarize_ticket',
  exposure: { kind: 'open' },
  llm_callable: true,
  base: {
    name: 'summarize_ticket',
    description: 'Load a support ticket and return a concise, safe operator summary.',
    parametersJsonSchema: {
      type: 'object',
      properties: {
        ticket_id: { type: 'string' },
      },
      required: ['ticket_id'],
    },
  },
  async handle(ctx) {
    const params = ctx.input;
    const ticket = await ctx.request('support-api', `/tickets/${encodeURIComponent(params.ticket_id)}`);
 
    const category = ticket.category || 'uncategorized';
    const needsVerification = category === 'account_access' && ticket.identity_verified !== true;
    const nextAction = needsVerification
      ? 'Verify identity before recommending account changes.'
      : 'Review the ticket details and answer from confirmed facts.';
 
    return {
      ticket_id: ticket.id,
      status: ticket.status,
      category,
      summary: ticket.summary,
      needs_verification: needsVerification,
      next_action: nextAction,
    };
  },
};

What happens at runtime

1. The user asks what to do with ticket T-100.
2. The agent calls summarize_ticket.
3. The tool loads the ticket through the support-api connection and applies deterministic classification rules.
4. The agent uses the returned fields to explain confirmed facts, missing data, and the next operator action.

Describe when to use the tool so the model can select it for the right request.

Custom Tool Definition

Custom tools have a handler that runs code. Use them for logic beyond a single connection request: calculations, data transformation, conditional workflows, or calls to systems that don't have a clean REST API.

export default {
  id: 'classify_ticket_priority',
  exposure: { kind: 'open' },
  llm_callable: true,
  base: {
    name: 'classify_ticket_priority',
    description: 'Classify support ticket priority from category, customer impact, and age.',
    parametersJsonSchema: {
      type: 'object',
      properties: {
        category: {
          type: 'string',
          description: 'Ticket category, such as account_access or billing',
        },
        affected_users: {
          type: 'number',
          description: 'Approximate number of affected users',
        },
        age_hours: {
          type: 'number',
          description: 'How long the ticket has been open',
        },
      },
      required: ['category', 'affected_users', 'age_hours'],
    },
  },
  async handle(ctx) {
    const params = ctx.input;
    const isSecuritySensitive = params.category === 'account_access';
    const hasBroadImpact = params.affected_users >= 10;
    const isStale = params.age_hours >= 24;
 
    const priority = isSecuritySensitive && hasBroadImpact ? 'high' : hasBroadImpact || isStale ? 'medium' : 'normal';
 
    return {
      priority,
      reasons: {
        security_sensitive: isSecuritySensitive,
        broad_impact: hasBroadImpact,
        stale: isStale,
      },
    };
  },
};

The handler calculates priority from explicit conditions. Test these conditions directly in code.

Tool Metadata

Define tool metadata and the handler in amodal/tools/<name>/tool.ts.

Confirmation Tiers in Practice

Connection policies and custom-tool metadata control approval through different fields. Confirmation Model documents how the runtime applies each surface.

For a custom tool, set exposure: {kind: "requires-confirmation"} in tool.ts to pause for approval. tool.json's confirm: true | "review" marks the tool non-read-only, allowing write-intent ctx.request calls, but does not itself prompt the user.

For connection policy.json endpoints:

Connection policies do not accept confirm: false. In tool.ts, enabled: false prevents registration, and llm_callable: false hides the tool from the model while retaining programmatic access. The tool.json loader does not apply enabled and does not support llm_callable; do not use those fields there as access controls. A tool.json with confirm: "never" skips registration with a warning. Connection policies also support "never" to deny an endpoint.

For a support workflow:

1. Allow permitted ticket reads without confirmation.

2. Set confirm: true on the connection endpoint for adding a public comment. For a custom tool that prepares and submits the comment, use exposure.kind: "requires-confirmation".

3. Set confirm: "review" on an endpoint that must be handled by a separate operator workflow. The agent receives a refusal; a chat approval does not execute it.

4. For batch changes, make the records and proposed changes explicit in the approval parameters. Batch size does not automatically select a confirmation tier.

5. Deny an endpoint with confirm: "never", or disable a tool.ts tool with enabled: false.

Handler Context

A tool.ts handler receives ctx and reads parameters from ctx.input. A handler.ts default export receives (params, ctx). Composition and durable methods require the handler.ts + tool.json layout described in Agent Workflows.

Common context members:

ctx.env() uses the env allowlist in tool.json. The tool.ts layout loads an empty allowlist, so ctx.env() returns undefined there.

Tools with "execution": "durable" in their tool.json additionally get journaled pause/resume methods: ctx.requestInput, ctx.waitForApproval, ctx.sleepUntil, the ctx.step(name, fn) checkpoint for expensive handler-local work, and the replay-frozen ctx.now / ctx.random. See Durable Tools.

ctx.request in practice

The request method resolves the connection's base URL, attaches credentials and sends the authored HTTP request. It does not enforce endpoint permissions or response field restrictions. It also omits request approval, automatic retries, and native OpenAPI validation. Enforce authorization and required approval in the authored workflow or downstream API.

For authored HTTP requests, a tool whose exposure is open resolves to read-only: ctx.request rejects write-intent calls unless the tool declares exposure: { kind: "requires-confirmation" } or tool.json sets confirm: true. A read-only POST endpoint can use explicit intent: 'read'.

export default {
  id: 'open_cpu_incident',
  exposure: { kind: 'requires-confirmation' },
  base: {
    /* description, parametersJsonSchema */
  },
  async handle(ctx) {
    const params = ctx.input;
 
    // Connection credentials are applied by ctx.request.
    const metrics = await ctx.request('datadog', '/api/v1/query', {
      params: {
        query: `avg:system.cpu.user{host:${params.hostname}}`,
        from: params.startTime,
        to: params.endTime,
      },
    });
 
    // This write is covered by the tool's approval.
    const incident = await ctx.request('pagerduty', '/incidents', {
      method: 'POST',
      data: {
        incident: {
          type: 'incident',
          title: params.title,
          service: { id: params.serviceId, type: 'service_reference' },
          urgency: params.urgency,
        },
      },
    });
 
    return {
      cpuAverage: metrics.series[0]?.pointlist?.map(([ts, val]) => val) || [],
      incidentId: incident.incident.id,
    };
  },
};

ctx.exec for shell commands

Use ctx.exec for operations that don't map to a REST API, such as data processing, file manipulation, or calling CLI tools.

export default {
  id: 'count_failed_jobs',
  exposure: { kind: 'open' },
  base: {
    /* description, parametersJsonSchema */
  },
  async handle(ctx) {
    // Run a database query via CLI
    const result = await ctx.exec('node scripts/count-failed-jobs.js', {
      timeout: 10000,
    });
 
    const parsed = JSON.parse(result.stdout);
    return { failedJobsLastHour: parsed[0].failed_jobs };
  },
};

Naming Convention

Tool names must be snake_case: lowercase letters, digits, and underscores, starting with a letter. Example: create_ticket, fetch_ticket, classify_priority.