External Api Connector

📸 Screenshots

Here are visual examples of this section:

External Api Connector - Worker Configuration Interface

The External API Connector transforms any HTTP endpoint into an agent-callable tool. It provides comprehensive configuration options including authentication, parameter schemas, rate limiting, and automatic retries. This worker enables agents to interact with external APIs seamlessly while maintaining proper error handling and request management.

2. Configuration Parameters

toolName: Name of the tool as it appears to the agent (defaults to "external_api")
toolDescription: Description of what the tool does for the agent's understanding
endpoint: The HTTP endpoint URL to call (supports path parameters with {paramName} syntax)
method: HTTP method to use (GET, POST, PUT, PATCH, DELETE)
params: Static parameters to include with every request as JSON string
paramsSchema: JSON array defining parameter schema for dynamic arguments
headers: HTTP headers to include with requests as JSON object
timeout: Request timeout in milliseconds (default: 10000)
authType: Authentication method (none, basic, bearer, api_key, oauth2_client_credentials)
username: Username for basic authentication
selectedKeyName: Name of the stored API key to use for authentication
oauth2TokenUrl: Token endpoint URL for OAuth2 client credentials flow
oauth2ClientId: Client ID for OAuth2 authentication
oauth2Scope: OAuth2 scope to request (optional)
rateLimitPerMinute: Maximum requests per minute (default: 60)
maxRetries: Number of retry attempts for failed requests (0-5, default: 2)

3. Input/Output Handles

tool: Input handle - receives tool execution requests from agents
response: Output handle - returns successful API response data
error: Output handle - returns error messages when requests fail

4. Usage Examples with Code

// Example parameter schema for a weather API tool
const paramsSchema = [
  {
    "name": "city",
    "type": "string",
    "description": "City name to get weather for",
    "required": true
  },
  {
    "name": "units",
    "type": "string", 
    "description": "Temperature units (metric or imperial)",
    "required": false
  }
]

// The worker will create a tool that agents can call like:
// await weatherTool({ city: "New York", units: "metric" })

5. Integration Examples

This worker is essential for connecting agents to external services like weather APIs, database endpoints, or third-party platforms. It automatically handles authentication, rate limiting, and retries, making it ideal for building robust agent workflows that depend on external data sources.

6. Best Practices

Define clear parameter schemas to help agents understand required inputs
Set appropriate rate limits to avoid overwhelming external APIs
Use path parameters in URLs for RESTful endpoints like /users/{userId}
Configure retries for unreliable endpoints but keep maxRetries reasonable
Store sensitive credentials using the selectedKeyName parameter rather than hardcoding

7. Troubleshooting Tips

Check that the endpoint URL is accessible and returns expected response formats
Verify authentication credentials are properly stored and referenced by selectedKeyName
Monitor rate limiting if requests are being rejected - adjust rateLimitPerMinute accordingly
Review parameter schema JSON syntax if the tool isn't receiving expected arguments