Agent-CoreX Documentation

Execute Tool Endpoint

POST /v1/execute_tool Execute a tool with specified parameters and get results.

Request Body

{
  "tool_name": "create-pull-request",
  "params": {
    "repository": "owner/repo",
    "title": "Add new feature",
    "from_branch": "feature/x",
    "to_branch": "main"
  },
  "timeout": 30000
}

Parameters

Parameter	Type	Required	Default	Description
`tool_name`	string	Yes	-	Name of tool to execute
`params`	object	Yes	-	Tool-specific parameters
`timeout`	integer	No	30000	Timeout in milliseconds

Response

{
  "success": true,
  "data": {
    "tool_name": "create-pull-request",
    "status": "success",
    "result": {
      "pr_number": 123,
      "pr_url": "https://github.com/owner/repo/pull/123",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "execution_time_ms": 245,
    "tokens_used": {
      "input": 150,
      "output": 200
    }
  },
  "meta": {
    "request_id": "exec_def456",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Examples

Create GitHub PR

curl -X POST "https://api.agent-corex.com/v1/execute_tool" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "create-pull-request",
    "params": {
      "repository": "owner/repo",
      "title": "Fix critical bug",
      "from_branch": "hotfix/bug-123",
      "to_branch": "main",
      "body": "This PR fixes a critical production bug"
    }
  }'

Deploy to AWS

curl -X POST "https://api.agent-corex.com/v1/execute_tool" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "deploy-aws-lambda",
    "params": {
      "function_name": "my-function",
      "zip_file": "function.zip",
      "environment": "production"
    }
  }'

Using SDK

const result = await agent.executeTool({
  toolName: 'create-pull-request',
  params: {
    repository: 'owner/repo',
    title: 'New feature',
    from_branch: 'feature/x',
    to_branch: 'main'
  }
});

console.log(`PR created: ${result.result.pr_url}`);

Error Responses

Tool Not Found (404)

{
  "success": false,
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'create-pull-request' not found or not connected"
  }
}

Invalid Parameters (400)

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required parameter: repository",
    "details": {
      "parameter": "repository",
      "reason": "required"
    }
  }
}

Timeout (504)

{
  "success": false,
  "error": {
    "code": "TIMEOUT",
    "message": "Tool execution timed out after 30000ms"
  }
}

Execution Failed (500)

{
  "success": false,
  "error": {
    "code": "EXECUTION_ERROR",
    "message": "Failed to create PR: Branch does not exist",
    "details": {
      "tool_error": "Invalid branch name"
    }
  }
}

Best Practices

Always handle errors

try {
  const result = await agent.executeTool({...});
} catch (error) {
  if (error.code === 'TOOL_NOT_FOUND') {
    // Guide user to connect tool
  }
}

Set appropriate timeouts
- Quick operations: 5-10 seconds
- API calls: 15-30 seconds
- Infrastructure tasks: 60+ seconds
Validate parameters before executing
- Check required fields
- Validate formats (URLs, names, etc.)

Implement retry logic

const executeWithRetry = async (toolName, params, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await agent.executeTool({ toolName, params });
    } catch (error) {
      if (error.code === 'RATE_LIMITED' && i < maxRetries - 1) {
        await delay(1000 * Math.pow(2, i)); // Exponential backoff
      } else {
        throw error;
      }
    }
  }
};

Next Steps

Retrieve Tools

Find tools before executing.

Real Examples

See execution flows.

Error Handling

Common error codes.

Ready to execute tools? See sample queries for real workflows! 🚀

API Reference

Tools

Servers

System

Execute Tool Endpoint

Execute Tool Endpoint

Request Body

Parameters

Response

Examples

Create GitHub PR

Deploy to AWS

Using SDK

Error Responses

Tool Not Found (404)

Invalid Parameters (400)

Timeout (504)

Execution Failed (500)

Best Practices

Next Steps

Retrieve Tools

Real Examples

Error Handling

​Execute Tool Endpoint

​Request Body

​Parameters

​Response

​Examples

​Create GitHub PR

​Deploy to AWS

​Using SDK

​Error Responses

​Tool Not Found (404)

​Invalid Parameters (400)

​Timeout (504)

​Execution Failed (500)

​Best Practices

​Next Steps

Retrieve Tools

Real Examples

Error Handling

Execute Tool Endpoint

Request Body

Parameters

Response

Examples

Create GitHub PR

Deploy to AWS

Using SDK

Error Responses

Tool Not Found (404)

Invalid Parameters (400)

Timeout (504)

Execution Failed (500)

Best Practices

Next Steps